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Foreword 


Welcome to the world of microcomputers opened to you by your eight-bit micro- 
processor. Welcome also to the world of appllcatlon software accessible with your 
Digital Research CP/M Plus" operating system, also called CP/M@ 3. Digital Research 
des~gncd CP/M 3 especially for rhe 8080, 8085, 2808 or equivalent mzcroproccssor 
that a the heart of your computer. 


What CP/M 3 Does For You 


CP/M 3 manages and supervms your computer's resources, including memory and 


d i t storage, the console (- 
and keybeyboard), printer, and mmmunications d w i a . 


It also manages information stored magnetically on disks by grouping this informa- 
tion into files of omerams or data. CP/M 3 can coo" files from a disk to "our 
. " 
~ , ~ - 


rompurrr'v memory, or to a pcrtphcral devtcr such ar a prtntrr To do ~ h a . (:P %I 
3 


placer var~our prugram, m memory and cxmtcr them ~n roponrc to commands you 
enter at your console. 


Once in memory, a program executes through a set of steps that instruct your 
computer to perform a cenain task. You can use CP/M 3 to create your own pro- 
grams, or you can choose from the wide variety of CP/M 3 application programs 
that entenain you, educate you, and help you solve commercial and sdmtific problems. 


What You Need to Run CP/M 3 om Your Computer 


Dieital Research nrovides ouo kinds of CP/M 3 rvstems: bankcd and nnnbanked. 
~ 
-~~ - 
~, 
~ 
- 
- - - . . 
. 


Your cumpurcr dcalcr can tell you ~f you have a bankcd or nonbankcd ryrtcm. 'lhc 
- 
banked rv,rrm rrqulrrr more memory, bur tn turn provnder more memory space for 
application programs. Ihe bankcd version also has additlorla1 enhancements that are 
noted in the text. 
- 
The mtnimum hardware requirement for both versions of CP/M 3 is a computer 
based on an 8080, 8085, or equrvalcnt micropromsor, a console dev~cc (generally a 
keyboard and display devtce such as a CRT screen), and at least one floppy dlsk 
- 
drive. To use all the capabilities of CP/M 3, you should have two disk dnves. At 
least one should be a slngle density floppy dnve, because CP/M 3 and most CP/M 
applications are distributed on single density floppy dirks. 
- 


The nonbankcd system rcquim at least 32K (kilobytes) of Random Access Mem- 
ory (RAM). The larger banked system requires at least 96K of RAM. If you want to 
expand beyond these requirements, you will appreciate that the banked system can 
indudc up to sixteen banks of memory. 


CP/M 3 and its utility programs are distributed on two floppy dish. The system 


disk contains the operating system and the most commonly used utility programs. A 
second disk contains additional utilities. 


How To Use CP/M 3 Docvmmtntion 


The CP/M 3 documentation set include three manuals: 


CP/M Plur (CP h( Vnrton 3, Opernnng Syrrem User's Gude 


m CP M P l u [CP M Verrton 31 Operortnl: System Propommrr'r Gut& 


Propammer'r Urtbrtrr Guide for the CP M Fomtl) of Operaring 5)rrrmr 


The CPlM Plus (CP/M Version 3) Operating System User's Gufde introduces you 
to the CP/M 3 operating system and tells you how to use it. The User's Guide 
assume that the vcraon of CP/M 3 on your distribution disk IS ready to run on your 
computer. To use this manual, you must be familiar with the pam of your computer, 
know how to set it up and Nm it on, and how m handle, inscn, and store disks. 
However, you do not need a great deal of experience with computers. 


The CPlM Plur (CP/M Vnsion 31 Osemtin. Svrtem Proerrlmmcr's Guide mmnn 
7 
" , 


~nformar~on 
for appl~cnrnon programmers who am manng or adapr~ng programs to - 


run under CP U 3 T h c P~o,erammer'r Urtlrrler Gutde for rhr CP M F~mtly of Oper 
rlting System includes infomatton on the CP/M a~semblcn and dcbuggcrs that cxpc- 
rienced programmers use to create nnu CP/M 3 programs. 
- 


How This Guide is Orgnnired 


This guide begins with slmplc examples, 
with basic concepts, then pee- 


sents a derailed reference section on commands. The fint four sections desctibe - 


CP/M 3 operation for the first-tlme user. Scction 1 introduces CP/M 3 and tells you 
how to stan the operating system, enter commands, edzt the command line, and 
create back-up copses of your distribution dsks. Section 2 d~scusses files, disks, and - 
drives. Scaton 3 desctibes how you can use CPlM 3 to manage your printer and 
console. Section 4 develops the concepts you need to use CP/M 3 commands. If you 
are new to CP/M, read the fint four sections carefully to get a general undersrandtng - 
of how to use CP/M 3 before you proceed to the specific command dcscnptions. 


- 


Section 5 omvidcs detailed information on each CP/M 3 utilirv oronram. amanzed 
- 
. 
- 


alphabetically for easy reference. Many of these arc programming utilities that you 
will nor use until you start writing your own CP/M 3 programs. Section 6 tells you 
how to uw ED, the CPiM 3 file editor. With ED, you can create and edit program 
- source codes, ton, and data files. 


Appendix A lists the messages CP/M 3 displays when it mcounvrs spcdal condi- 
tions, and describes corrmive action where necessary. Appendix B provides an ASCII 
to hcradcc~mal conversion table. Appendix C lists the filetypes arsoclatcd with 
CP/M 3. Appendix D lists and defines the CP/M 3 control characters. Appendix E 
provldes a glossary of commonly used computer terms. 


If you are new to computers, you might find some of the topics, such as the 


pmgrammmg ctilitics, difficult to understand at first. Learning to use your computer 
a a challenge, and we hope you will find a fun. This book proceeds step-by-step so 
that you can qurckly proceed from opming your new system dirk package to master- 
ing CPiM 3's powerful facilities. 
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Section 1 
Introduction to CP/M 3 


This section tells you how m start CP/M 3, how m enter and edit the command 
- 
\me, and how to make back-up copies of your CP/M 3 distribution disks. 


1.1 How to Stan CP/M 3 
- 


Starting or loading CP/M 3 means reading a copy of the operating system from 
your CP/M 3 system disk (1 of 2 of your distribution disks) into your computer's 
- 
memory. 


First. check that "our mmauter's wwer is an. Next. insert the CP/M 3 svstem 
- ~~.., 
.~~ , 
~ - - - ~ ~ ~ r 
~ 
~ , 
~ 
~ 
~ 
, 
~ 
~~~~ 


disk into your inntial dtive. In thss section, assume that the initial dtive is A and the 
- 
dsk is removable. Close the drive door. Then, press the RESET or RESTART bunon. 
This automatically loads CP/M 3 into memory. This process is called booting, cold 
starting, or loading the system 
- 


After CP/M 3 is loaded into memory, a message similar m the following is dis- 
played on your screen: 
- 
CP/M 3 
Version V.V 


The versroo number, represated above by V.V, ells you the version of CP/M 3 that 
- 
you own. After this display, the following ovo-character message appears on your 
screen: 


This rs the CP/M 3 system prompt. The system prompt tells you that CP/M 3 is 


ready to read a command horn your keyboard. In this example, the prompt also tells 
- 
you that drive A rs your default drive. This means that unttl you tell CP/M 3 to do 
otherwise, it lwks for program and data files on the disk in drive A. It also tells you 
that you arc logged in as user 0, by the absence of a user number other than 0. 
- 


1.2 The Command Line 


CP/M 3 performs tasks according to specific commands that you type at your 


keybard. A CPM 3 m 
m 
d 
linc rs c o m p d of a mmmand h r d , an optional 
mmmand tail, and a carriage return keystroke. The command keyword identifies a 
mmmand (program) to be executed. The command tail can conrain cxrn informa- 
tion for the command, such as a filename or parameters. To end the command line, 
you must press the carriage rrmrn or ENTER key. The followtng example shows a 
command line. 


The characters that the uxr types are danred to distinguish them from characters 
that the system displays. In this example, DIR is the command keyword and MYFILE 
is the command tad. The carriage return keystroke does nor appear on the screen or 
m the example. You must remember to press the carriage return key to send a 
command line to CP/M 3 for processing. Note that the carriage return key can bc 
marked ENTER, RETURN, CR, or something similar on your keyboard. In this 
guide, RETURN signifies the carriage return key. 


As you type characters at the keyboard, they appear on your screen. The single- 
character posttion indicator, called the cursor, moves to the right as you type char- 
acters. If you make a typing error, press either the BACKSPACE key (if your key- 
board has one) or CTRL-H to move the cursor to the left and correct the error. 
CTRL is the abbreviation for the Control key. To type a control character, hold 
down the Control key and press the required letter key. For example, to move the 
cunor to the leh, hold down CTRL and press the H key. 


You can type the keyword and command tail in any combination of upperiasc 


and lower-case Imers. CP/M 3 treats all lmers in the command linc as upper-care. 


Generally, you type a command line directly after the system prompt. However, 


CP/M 3 does allow spaces between the prompt and the command keyword. 


CP/M 3 recognizes two different types of commands: built-in commands and man- 


sient utility commands. Burlt-in commands cxccute programs that reside in memory 
as a pan of the CP/M 3 operating system. Built-in commands can be executed imme- 
diately. Transient utility commands are stored on disk as program files. They must 
be loaded from disk to perform thcir task. You can recognize transient utility pro- 
gram files when a dlremry IS displayed on the sueen because their filenames are 
followed by COM. Smion 4 presents lists of the CP/M 3 built-in and translent utility 
commands. 


For transient utiliuc~, CP/M 3 checks only the mmmand keyword. If you xndude 


a command tail, CP/M 3 passes rt to the utility without checking it because many 
utilities require unlque command tails. A command tail cannot contain more than 
128 characters. Of course, CP/M 3 cannot read either the command keyword or the 
command tar1 untd you p m s the RETURN key. 


Let's use one command to demonstrate how CP/M 3 reads command lines. The 


DIR command, which is an abbrevration for directory, tells CP/M 3 to display a 
dimcmry of dlsk file on your screen. Type the DIR keyword afm the system prompq 
omit the command tail, and press RETURN. 


A > D I R 


CP/M 3 responds to this command by writing the names of all the files that are 
stored on the disk m drxve A. For example, if you have your CP/M 3 system disk in 
dnve A, these filenames, among others, appear on your screen: 


COPYSYS 
c o n 


P I P 
c o w 
SET 
C o n 


1.2 The Command Line 
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CP/M 3 recognizes only correctly spdled command keywords. If you make a typ- 
ing error and press RETURN before a r m i n g your mistake, CP/M 3 echoes the 
ammand line followed with a question mark. If you mistype the DIR command, as 
in the following example, CP/M 3 responds 


PI>OJR 
DJR? 


to tell you that it cannot find the command keyword. To correct simple typing errors, 
use the BACKSPACE key, or hold down the CTRL key and press H to move the 
cursor to the left. CPM 3 sumom other control characters that help you efficiently 
edtt command lines. Section Ptells how to use control characters m edlt command 
hnes and other information you enter at your console. 


DIR accepts a filename as a command tail. You can use DIR with a filename to 


see ~f a specific file is on the disk. For example; m check that the transient utility 
program COPYSYS.COM is on your system disk, type 


A>OIR COPYSYS.COM 


CP/M 3 performs ths task by displaying either the name of the file you specified, or 
the message 


Be sure you type at least one space after DIR to separate the command keyword 
from the command tail. If you do not, CP/M 3 responds as follows. 


1.3 
W h y You Should Back Up Your Files 


Humans have fiulrs, and so do compunrs. Human or computer errors sometimes 
destroy valuable programs or data files. By mistyping a command, for cxamplc, you 
could accidentally erase a program that you just created or a data file that has been 
months in thc making. A sunilar disaster could m l t from an electronic component 
failure. 


- 
CP/M 3 User's Guide 
1.3 Why You Should Back Up Yoor Files 


- 
Data processing professionals avoid losing programs and data by making copies of 
valuable files. Always make a working copy of any new program that you purchase 
and save the oriinal. If the Droeram is accldcntallv erased from the workinp. CODY. 
. - 
- .. 
- 
you can easily restore it from the original. 


It is also wise to make keauenr moles of new oroerams or data files as vou 
. 
. 
. .. 


develop them. The hequcncy of making copncs vanes wtrh each programmer. How- 
- 
ncr, as a grncral rulc, make a copy at rhc po~nt whrrc It taka tcn to rwcnry rlmc5 
longer to rrrntrr the ~nformatton than #r take- lo make rhc copy. 


So far, we have not discussed any commands that change ~nhrmation recorded on 
- 
your CP/M 3 system disk. Before we do, make a few working mpier of the your 
distribution disks. 
- 


1.4 How to Make Copies of Your CP/M 3 Disks 
- 
To back up your CP/M 3 dirks, you need two or more floppy disks h r the back- 
ups. The back-up disks can be new or used. You might want to format new, or 
reformat used disks wlth the disk fomatt~ng program that accompanies your partic- 
- 
ular computer. If the disks are used, be sure that there are no other files on the dirks. 


If your computer's manufacturer has provided a special program to copy daks, 


you mighr use it to make back-ups of your distribution disks. Otherwise, use rhe 
- 
COPYSYS and PIP utility programs found on your CP/M 3 dirtriburlon disks. PIP 
can copy all program and data filer, but only COPYSYS can copy the operating 
system. Note thar the COPYSYS utility dlrtributed by Digital Rerarch only funr- 
- 
tions with ctghr-inch, single-density drives. However, your computcr'r manufacturer 
mighr have modifled COPYSYS to work with your equipment. 


- 
This section shows how to make distribution disk back-ups on a system that has 
two drives: drwe A and drivc 8. Your drives might be named with other lenen kom 
the range A through P. To make a mpy of your CP/M 3 dlstrlburion system disk, 
labeled 1 of 2, first use the COPYSYS utility to mpy the operating system loader. 
- 
Make sure thar your distribution system dlsk is m drlvc A, the default drive, and the 
blank disk is in drive B. Then enter the fallowing mmmand at the system prompt: 


- 


B DIGITAL RESEARCH'" 


1-5 
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CP/M 3 loads COPYSYS into memory and runs it. COPYSYS displays the following 
output on your screen. When the program prompts you, press RETURN only when 
you have verified that the correct disk is in the c o r m dnve. 


C O P Y S Y S V e r 3.0 


Source d r i v e n a m e l o r r e t u r n f o r d e f a u l t ) 
?A 


S o u r c e o n R t h e n t y p e r e t u r n 


Function c o m p l e t e 


O e s t l n a t l o n d r i ~ e 
name l o r r e t u r n t o r e b o o t 1 -8 


D e s t l n a t ~ o n on 6 t h e n t y p e r e t u r n 


F u n c t i o n o o n ~ l e t e 


Do r o u u i s h t o C O P Y C P N ~ , S Y S ~ Y ~ S 


(CP/M 3 repeats the above prompts m copy CPM3.SYS.) 


A > 


You now have a copy of the operating system only. To copy the remaining files from - 
dlrk 1 of 2, enter the following PIP command. 


This PIP command copies all the files in your disk directory to drive B from drive A. 
PIP displays the message COPYING followed by each filename as the copy operation 
proceeds. When PIP finlshes copymg, CP/M 3 displays the system prompt. 
- 


Now you have an exact copy of the distribut~on drsk 1 of 2 in drive B. Remove 


the original from drive A and store a in a rak place. If your orlglnal remalnr safe - 
and unchanged, you can easily restore your CP/M 3 program files ~f something 
happens to your working copy. 


CP/M 3 User's Guide 
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Remove the copy kom drive B and rnscn it m drive A. Use this copy as your 


CP/M 3 systcm disk to make more back-ups, to try the examples shown throughout 
this manual, and to stan CP/M 3 the ncn time you rum on your computer. Cold 
start the computer to check copy operations. 


You still need to make a back-up copy of distribution disk 2 of 2. Thxs disk 
contains programmer's utility programs and source filer. Place another new or refor- 
maned disk in drive B. This time, type only the command keyword: 


PIP responds with an arrenrk prompt, '. You can now remove disk 1 of 2 from 
drive A and insen the disk you want to copy, dlrk 2 of 2. Type the following PIP 
command after the asterisk prompt, for example, 


Again, PIP displays the message COPYING, followed by each filename. When PIP 
mmpleres the copy and displays the asterisk prompt, press RETURN. CP/M 3 then 
displays the familiar A> system prompt. You now have a copy of disk 2 of 2 m 
drive B. Remove both 2 of 2 dlsks and store them tn a safe place. You can now 
reinscn your working system disk and continue to use the system. 


End of Section 1 
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Section 2 
Files, Disks, and Drives 


CP/M 3's most important task rs to access and maintain files on your dirks. Wcth 


CP/M 3 you can create, read, write, copy, and erase dirk files. This section tells you 
what a file IS, how to create, name, and access a file, and how files are stored on 
your disks. It also tells how to change disks and change the default drive. 


2.1 What is a File? 


A CP/M 3 file is a collect~on of related information stored on a disk. Every file 
must have a unique name because CP/M 3 uses that name to access that file. A 
directory is also stored on each disk. The directory contains a list of the filenames 
stored on that disk and the locations of each file on the disk. 


In general, there arc two kinds of files: program (command) files and data files. A 


pmgram file contains an executable program, a series of insmmons that the unn- 
putcr follows step-by-step. A data filc 13 usually a collection of informauon: a list of 
names and addresses, th; inventory of a store, the accounting records of a business, 
the text of a document, or similar related mformation. For example, your computer 
cannot execute names and addresses, bur it can execute a pmgram that prints names 
and addresses on mailing labels. 


A data file can also contain the source mde for a progam. Generally, a program 
source filc must be orocessed bv an assembler or comoiler before it becomes a or"- 
7 
~ 
gram file. In mos cnrcr. an cxccurlng program proccrrcv a data file Howcvcr, there 
are ttmr, when an cxrcurlng program pruccsxs a program hlr. For example, rhr 
ropy program PIP can copy one or more program filcr. 


2.2 How Are Files Created? 


There are many ways to create a filc. One way ir to u s a t a r editor. The CP/M 3 


mn ediror ED [dcrcrrbed in Smion 6) can create a file and assign it the name you 
specify. You can also create a file by copying an exlrting filc to a new location, 
perhaps renaming it in the proass. Under CP/M 3, you can use the PIP command to 
copy and m a m e files. Finally, some programs such as MAC" mate output files as 
they process input files. 
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2.3 How Are Files Named? 


CP/M 3 ldcntifies every file by its unique file specdcation. A file specification can 
be simply a one- to eight-character filename, such as: 


MYFILE 


A filc spec~fication can have four parts. a drive specifier, a filename, a filetype, and 
a password. 


The drive specifier is a single lmer (A-P) followed by a colon. Each drive ~n your 


system is assigned a letter. When you indude a drive spwfier as pan of the file 
spec~fication, you are telling CP/M 3 that the file is stored on the disk currently in 
that drive. Far example, 11 you enter 


CP/M 3 looks m drwe B for the file MYFILE. 


The filename can be from one to eight charancn. Whm you makc up a filename, 
try m let the namc tell you somnhlng about what the filc contains. For example, if 
you have a llst of customer names for your businas, you could namc the file: 


CUSTOUER 


so that the name gives you some tdca of what is in the filc. 


As you begin to use your computer with CP/M 3, you will find that files fall 
naturally into categories. To help you identify files belonging to the same category, 
CP/M 3 allows you to add an optional one- to three-character utenaon, called a 
filetype, to the filename. When you add a filetype m the filename, separate the filetype 
from the filename with a period. Try to use three lenen that tell something about 
the file's category. For example, you could add the following filetype to the file that 
contains a list of customer nama: 


When CP/M 3 displays file specifications in response to a DIR command, it adds 
blanks to shon filenames so that you can compare filetypes quickly. The program 
files that CP/M 3 loads into memory from a disk have different filenames, but all 
have the filetype COM. 


- 
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In hanked CP .M 3, you can add a p a ~ ~ w o r d 
ar an oprlonal pan of the file ,pcc~fi- 
- 
catton Ihr pasword can bc from one to etghr characten If you nnrludc a parsword, 
wparste ~t from the filcrypc (or hlcnamc, tf no filrrypr Ir tncludcd wnrh a rcm~colon. 
as follows: 


If a file has been protected with a password, you must ENTER the password as pan 
of the file specification to access the file. Section 2.7.3 describes passwords in more 
detail. 


We recommend that you create filenames, filetypes, and passwords from letters 
and numbers. You must not use the following characters in filenames, filetypes, or 
passwords because they have spcclal meanings for CP/M 3: 


A mmplcrc file rpc~~ficar~on 
conratnnng all porrtblc rlcmcnrs conrwtr of a Jrlve 


speoficat~on, a pnmary filcnamr, a hlctypc. and a par~word, all separated by rhclr 
appropnarc drlomttrrr, as ~n the follownng rxrmplc 


2.4 Do You Have the Correct Drive? 


When you type a file specification in a command tail without a drive specifier, the 


program looks for the file in the dr~ve named by the system prompt, called the 
default drive. For example, if you type the command 


DIR looks in the dtrectory of the disk in drive A for COPYSYS.COM. If you have 
another drive, B for example, you need a way to tell CP/M 3 to access the disk in 
drive B instead. For this rearon, CP/M 3 lets you precede a filename with a drive 
specifier. For example, m response to the command 


2.4 Do You Have the Cnrcct Drive? 
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CP/M 3 looks for the file MYFILE.LIB in the d~rcctory of the disk in drive B. When 
you give a command to CP/M 3, note which disk is in the default drive. Many 
apphcatzon programs require that the data files they access be stored in the default 
drive. 


You can also precede a program filename with a drive specifier, even if you use the 
program filename as a command keyword. For example, if you type the following 
command 


CP/M 3 looks in the directory of the disk in drivc B for the file PIP.COM. If CP/M 3 
finds PIP on drive B, it loads PIP into memory and eXFCuteS it. 


If you need to access many files on the same dnve, you might find it convenient to 
change the default drive so that you do not need to repeatedly enter a drive specifier. 
To change the default dnve, enter the drive specifier next to the system prompt and 
press RETURN. In response, CP/M 3 changes the system prompt to display the new 
default drivc: 


A>B: 
B > 


Unlike the filename and filetype which arc stored in the disk directory, the drive 
specifier for a file changes as you move the disk from one drive to another. Therefore, 
a filc has a different file specification when you move a disk from one drive to 
another. Senion 4 presents more information on how CP/M 3 locates program and 
data files. 


2.5 Do You Have the Correct User Number? 


CP/M 3 further identifies all files by assigning each one a user number which 


ranges from 0 to 15. CP/M 3 assigns the user numbcr to a file when the file ir 
created. User numbers allow you to separate your files into sixteen file groups. User 
numbers are particularly uscfol for organizing files on a hard drsk. 


\Vhm you usc a CP M 3 utolmry to irearc a filc, the file 19 arr~gnrd to rhr currcnr 


uxr numbcr, unlcw you use PIP to copy the file to anurhcr user numhcr. You can - 
dcrcrmlnr the currcnr user numhrr by louk~ng st rhc system prompt. 
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40 > 
User number 4, drive A 


R > 
User number 0, drive A 


ZB > 
User number 2, drive B 


'Ihe user number always precedes the drive identifier. User 0, however, is the default 
user number and is not displayed in the prompt. 


You can use the built-in command USER to change the current user number. 


You can change both the user number and the drive by entering the new user 


number and drive specifier together at the system prompt: 


Most mmmands can access only those files that have the current user number. For 


example, if the current user number is 7, a DIR command with no options displays 
only the files that were created under user number 7. However, ~f a file resides in 
user 0 and is marked with a special file attribute, the file can be accessed from any 
user number. (Sectton 2.7.1 discusses file attributes.) 


2.6 Accessing More Than One File 


Certain CP/M 3 built-in and transient utilities can select and proass several files 
when special wildcard characters are included in the filename or filetype. A file spec- 
ification contalntng wildcards IS called an ambiguous filespec and can refer to more 
than one file because it gives CP/M 3 a pattern to match. CP/M 3 searches the dlsk 
directory and selects any file whose filename or filetype matches the pattern. 
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Remember that CP/M 3 uses wildcard patterns only while searching a disk direc- 
- tory, and therefore wildcards are valid only in filenames and filetypes. You cannot 
use a wildcard character in a drive specifier. You also cannot use a wildcard charac- 
ter as part of a filename or filetype whm you create a file 


2.7 How to Protect Your Files 


Under CP/M 3 you can organize your files into groups to protect them from 
accidental change and from unauthorized access. You can specify how your files are 
displayed in response to a DIR command, and monitor when your files were last 
accessed or modified. CP/M 3 supports these features by assigning the following to 
files: 


m user numbcn 


attributes 


1 time and date stamps 
1 passwords (banked CP/M 3 only) 


All of thls information for each file is recorded in the disk directory. 


2.7.1 
File Amihuter 


File attributes control how a file can be accessed. When you create a file, CPM 3 


gives it two attributes. You can change the attributes with a SET command. 


The first attribute can be set to either DIR (Directory) or SYS (System). This 
attribute mntrolr whether CP/M 3 displays the file's name m response to a DIR 
command or DIRSYS command. When you create a file, CP/M 3 automatically sen 
this attribute to DIR. You can display the name of a file marked wlth the DIR 
attribute with a DIR command. If you give a file the SYS amibutc, you must use a 
DIRSYS command to display the filename. Slmple DIR and DlRSYS commands dis- 
play only the filenames created under the current uscr number. 


A file with the SYS attribute has a special advantage when it is created under user 


0. When you give a file wrth user number 0 the SYS attribute, you can read and 
execute that file from any user number. This feature gives you a convenient way to 
make your commonly used programs available under any user number. Note, how- 
ever, that a user 0 SYS file does not appear in response to a DIRSYS command unless 
0 is the current uscr number. 
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The second file attribute can be set to either R/W (Read-Write) or WO (Read- 
Only). If a filc a marked WO, any attempt to write data to that file produces a Read- - 
Only error message. Therefore, you can use the WO amibute to protect important 
files. A file with the RIW attribute can be read or written to, or erased at any time, 
unless the disk is physically write-pmf~fcd. 
- 


2.7.2 
Date and Time Stamping 


If you use date and time stamps, you can quickly locate the most recent copy of a - 
file, and check when it was last updated or changed. You can choose to have the 
system tell you either when you created the file, or when you last read from or wmte 
to the filc. You use the SET command to enable dare and tlmc stamping, and the 
DIR command with the DATE option to display a file's time and date stamp. 
- 


A SET command enables the option you want to monitor. You can use the follow- 


mg commands to enable time and date stamplng on a dak, but you must choose - 
between ACCESS and CREATE. If you chwse ACCESS, the stamp records the last 
time the file was accessed. If you choow CREATE, the stamp records when the file 
was created. 


Files created on or copied m a disk that has time and date stamping are automati- 
cally stamped. The DATE command allows you to display and reset the txmc and 
date that CPM 3 is usmg. For a complete discussion of rime and date stamping, see 
the descriptions of the SET and INITDIR commands in Section 5. 


2.7.3 
Paswords (Banked CP/M 3 h l y ) 


Passwords allow you to protm your files from access by other users. You can use 
passwords to limit access to certain files for security purposes. 


The SET utility allows you to enable password protection on a drive, assign a 
password to SET itself (so that unauthorized users cannot disable password protec- 
tlon on a dnvc), and asstgn passwords to specific fils that have already been created. 
You can assign passwords to all program and data files. This means that a command 
line could require the entry of two passwords in order to execute: one password to 
access the command program, and a second password to access the file specified in 
the mmmand tail. 
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Some CP/M 3 commands and most word processing, amounting, and other appli- 
- cation programs running under CP/M 3 do not accept passwords in the command 
tail. If you want to protect your file and atdl use thwc programs, you can set a 
default password before executing the application program. See the description of 
- the SET command in Section 5 for an explanat~on of this process. 
- 2.8 HOW Are Files Stored on a Disk? 


CPlM 3 records the filename, filerype, password, user number, and attributes of 
each file in a special area of the disk called the directory. In the directory, CP/M 3 
- also mordr which pam of the disk belong to which file. 


CPlM 3 allocates directory and smrage space for a file as records are added to the 
- filc. When you erase a file, CP/M 3 reclaims storage in two ways: it makes the file's 


directow soace available m cataloz a dlffermt filc. and frees the file's storaee soace 
. . 
" . 


for later use. It is this dynamic allocation feature that m&es CP/M 3 powerful. You 
- do not have to tell CP/M 3 how big your file will become, because it automatically 
allocates more storage for a file as needed, and mleases the storage for reallocation 
whcn the file is erased. Use the SHOW command to determine how much space 
remains on the disk. 
- 


2.9 Changing Floppy Disks 
- 
CPlM 3 cannot, of course, do anything to a file unless the disk that holds the file 


ts inserted into a drive and the drive is ready. When a drsk is in a drive, rt is onltnc 
and CP/M 3 can access its directory and files. 
- 


At some time, you will need to take a disk out of a drive and llwert another that 


contains different files. You can replace an online disk whenever you see the system 
- prompt at your console. lhis is a clear indication that no program is reading or 
writing to the drive. 


You can also remove a disk and insert a new one when an appl~cation program 
- prompts you to do so. This can occur, for example, whcn the data that the program 
uses does not fit on one floppy disk. 
- Note: you must never remove a disk if a program is reading or writing to it 
- 
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You cm change dirks on the drivc without sending any spcdal signals to CPlM 3. 
This allows you to insert another disk at n program's request and read fils from or 
mate files on the new disk. 


2.10 Protecting a Drive 


Under CP/M 3, drives can be marked WO just ss fiks can be givm the WO 
attribute. The default state of a drive is RIW. You can give a drivc the RIO attribute 
by usmg the SET command described in Senion 5. To mum the drive to WW, use 
the SET command or press a C l R L C at the sysmn pmmpt. 


End of Section 2 
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Section 3 
Console and Printer 


This section describes haw CP/M 3 communicates with your console and printer. 


It tells how to start and stop console and printer output, edit commands you enter 
at your console, and redirect console and printer input and output. It also explains 
the conapt of logical devices under CP/M 3. 


3.1 Controlling Console Output 


Sometimes CP/M 3 displays information on your sueen too quickly for you to 
mad it. Sometimes an especially long display scrolls off the top of your screen before 
you have a chance to study ~ t . To ask the system to wait while you read the display, 
hold down the CONTROL (CTRL) key and press S. A CTRL-S keystroke causes the 
display to pause. When you are ready, press CTRL-Q to resume the display. If you 
press any key besides CTRL-Q durlng a display pause, CP/M 3 sounds the console 
bell or beeper. 


DIR, TYPE, and other CP/M 3 ut~litxcr support automatic paging at the console. 


Thns means that 11 the program's output is longer than what the screen can display 
at one time, the display automatically halts when the screen is filled. When this 
wcun, CP/M 3 prompts you m p m RETLlRN to continue. 


3.2 Controlling Printer Output 


You can also use a control command to echo console output to the pnntcr. To 
start printer echo, press a CTRL-P. To stop, press CTRL-P again. Wh~lc printer echo 
is in effect, any characterr that appear on your screen are listed at your printer. 


You can use printer echo with a DIR command to make a list of filer stored on a 


floppy disk. You can also use CTRL-P with CTRL-S and CTRL-Q to make a hard 
copy of pan of a file. Use a TYPE command to start a display of the file at the 
console. When the display reaches the part you need to print, press CTRL-S to stop 
the display, CTRL-P to enable printer echo, and then CTRL-Q to resume the display 
and start printmg. You can use another CTRL-S, CTRL-P, CTRL-Q sequence to 
termmate printer echo. 


3.3 Conmlc Line Editing 
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3.3 Console Line E d i ~ g 
- 


You can correct simple typing errors with the BACKSPACE key. CP/M 3 also 
supports additional line-editing functions for banked and "onbanked systems that 
you perform with control characters. You can use the control characters to edit - 
command lines or input lines to most programs. 


3.3.1 Lbe Editing in Nostbanked CP/M 3 
- 


Nunbanked CP M 3 allows you to cdtt your command ltnr urtng thc xr of char- 


anerr lmrted tn Tahlc 1.1. To cdtt a command lsne ~n nonhankcd CP M 3, u u control 
chaactcrs to dclnc chaactcrr I& of thc NMI, thm replace them wrh nnv chaancn - 


In the following example command line, the command keyword PIP is mlstypcd. 


The underbar represents the cursor. 


A>POP A : = 8 : r . r - 


To move the cursor to the lcncr 0, 
hold down the CI?U. key and press the letter H 
eleven times. CTRL-H dclctes characters as it moves the cursor left, leaving the 
following command line: 


n>p- 


Now, type the correct Icncrs, press RETURN, and smd the command to CP/M 3. 
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Table 3-1 hsu all line-editing control characters for "onbanked CP/M 3. 
- 


Table 3-1. Nonbankcd CP/M 3 Lineediting Conrml Charactm 
- 
1 Character 
I 
Meontnn 
I 


GIRL-E 
Forces a physical carriage return but does not send the com- 
mand line to CP/M 3. Mover the cursor to the beginning of the 
next line without erasing your previous mput. 


CTRL-H 
Deletes a character and moves the cursor lek one character 
parition. 


CTRL-I 
Moves the cursor to the n u t tab stop. Tab stops are automati- 
cally set at each eighth column. Has the same effect as pressing 
the TAB key. 


CTRL-J 
Sends the command line to CP/M 3 and returns the cunor to 
the left of the current Ime. Has the same effect as a RETURN 
or a CTRL-M. 


CTRL-M 
Sends the command line to CP/M 3 and m r n s the cursor to 
the lek of the current line. Has the same effect as a RETURN 
or a CTRL-J. 


CTRL-R 
Places a # at the current cursor location, moves the cursor to 
the next Imc, and d~splays any partla1 command you typed so 
far. 


CTRL-U 
Dxscards all the characters ~n the command line, plaas a # at 
the current cursor position, and moves the cunor to the next 
command hne. 


CTRL-X 
Discards all the characters in the mmmand line, and moves the 
cursor to the beamninp, of the current Ime. 


You probably noticed that some conrrol characters have the same meaning. Far 


example, the CTRL-J and CTRL-M keystrokes have the same effect as pressing the 
RETURN key; all t h m send the command line to CP/M 3 for processing. Also, 
CTRL-H has the same effect as presstng the BACKSPACE key. 
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3.3.2 Line Editing in Banked CP/M 3 
- 


Banked CP/M 3 allows you to edit your command line without deleting all char- 
acters. Using the hne-editmg control characters listed in Table 3-2, you can move the 
cursor left and right to ~nsert and delete characters m the middle of a command Imc. 
You do not have to retype everything to the r~ght of your cormtion. In banked - 


CP/M 3, you can pmss RETURN when the curror is in any position in the command 
Itne; CP/M 3 reads the entire command line. You can also recall a command for 
reed~ting and reexecution. 
- 


In the following sample session, the user misrypcd PIP, and CP/M 3 returned an 


aror message. The user recalls the erroneous command line by pressing CTRL-W - 
and correcrs the error (the underbar represents the cursor): 


R>PDP A:=B:*.*- 
(PIP mistyped) 


POP9 


R>POP A:=B:*.*- 
(CTRL-W recalls the line) 


A>POP 
- 
A : = B : + . * 
(CTRL-B to beginning of line) 


A>POP A : = B : * . * 
(CTRL-F to move cursor right) 
- 


A > P P A : = B : r + * 
(CTRL-G to delete error) 
- 


A > P I P e : = a : r . r 
(type I to correct the command name) 
- 


To execute the corrected command line, the user can press return even though the 


cursor is in the middle of the line. A return keystroke, or one of its equivalent control 
characters, nor only executes the command, but also stores the command in a buffer 
so that you can recall it for editing or reexecution by pressing CTRL-W. 


When you insert a character in the middle of a line, characters to the right of the 


cursor move to the right. If the line becomes longer than your screen 1s wtde, char- 
acters disappear off the right side of the screen. T h c ~ 
characters are not loot. lhey 


reappear ~f you delete characters from the line or if you press CTRL-E when the 
cursor is in the middle of rhe line. CTRL-E moves all characters to the right of the 
cursor to the next l~ne on the screen. 


Table 3-2 gives a complete ltst of line-editing control characters for a banked 


CP/M 3 system. 
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Table 3-2. Banked CP/M 3 L i n c s d i ~ g 
Control Characters 


I Character 
I 
Mconin~ 
I 


I a 
- 
A 
Moves the cursor one character to the Icft. 
I 


CTRL-B 
Moves the cursor to the beg~nning of the mmmand l~ne without 
having any effect on the contents of the line. If the cursor is at 
the beginning, CTRL-B mover a to the end of the line. 


CTRL-E 
Forces a physical carriage return but does not send the com- 
mand line to CP/M 3. Moves the cursor to the begnning of the 
next line without erasing the previous input. 


/ CTRL-F 
Moves the cursor one character to the right. 
I 


1 _L-G 
Deletes the chnractw indinid by the cursor. The cumr does 
not move. 


1 CTRL-H 
Deletes a charmer and moves the c u a r eft me character 
posalon. 


CTRL-I 
Moves the cursor to the next tab stop. Tab stops arc auromati- 
cally set at each eighth column. Has the same effect as pressing 
the TAB key. 


CTRL-J 
Sends the command line to CP/M 3 and returns the cursor to 
the beginning of a new line. Has the same effect as a RETURN 
or a CTRL-M keystroke. 


I CTRL-K 
Deletes to the end of the line from the cursor. 
I 
CTRL-M 
Sends the command l~ne to CP/M 3 and returns the cursor to 
the beginn~ng of a new linc. Has the same effect as a RETURN 
or a CTRL-J keystroke. 


CTRL-R 
Retypes the command line. Places a # at the current cursor 
location, mover the cursor to the next linc, and retypes any 
oanial command vou w e d so far. 
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Table 3-2. (continued) 


You probably noticed that some control characters have the same meaning. For - 


example, the CTRL-J and CTRL-M keystrokes have the same effect as pressing the 
RETURN key: all three send the mmmand line to CPlM 3 for o r o a ~ v m ~ . 
Also. 


Character 


CTRL-X 
Discards all the characters left of the cursor and moves the cur- 
sor to the beginning of the current line. CTRL-X saves any 
characters right of the cursor. 


. 
--. 


(TRI -11 har'rhc ramc cflcrr as prcrsonp the RACKSPACE key Norm that when a - 
control charanrr Ir dtrplaycd on your ,crccn. ,r Br prrccdcd hy an up-arrow, 1 For 
cxamplc, a (:TRI.-C krvrtroke rppcarv 3s T(: on "our w e n . 


- 


- 


3.4 Redirecting Input and Output 


Meoning 


CP/M 3's PUT command allows you to direct console or printer output to a disk - 


file. You can use a GET mmmand to make CPlM 3 or a uriliry program take console 
input from a disk file. The following examples illustrate some of the conveniences 
GET and PUT offer. 
- 


- 


CTRL-U 
Discards all the characters m the command line, places a # at 
the current cursor position, and moves the cursor to the next 
line. However, you can use a CTRL-W to mall any characters 
that were to the left of the cursor when you pressed CTRL-U. 


CTRL-W 
Recalls and displays previously entered command line both at 
the operating system level and with," executing programs, if the 
CTRL-W is the first character entered after the prompt. CTRL- 
1, CTRL-M, CTRL-U, and RENRN define the command line 
you can recall. If the command line conta~ns characters, CTRL- 
W moves the cursor to the end of the command line. If you 
press RETURN, CP/M 3 executes the recalled mmmand. 


- 
- 
- 
- 


- 
You can use a PUT command to direct conrole output to a dirk file as well as rhc 


onrole. With PUT, you can create a dirk file containing a direcrory of all files on that 
dlsk, as follows: 


1>DIR 
I : FILEHPHE TEX 
8 FRONT 
TEX 
2 FRONT 
MAR : ONE 
MIX I TYREE 
TEX 
l: 
FOUR 
TEX : ONE 
TEX i L I N E D 1 1 
TEX I E X l l l f l 
TXT : TYO 
BPX 


1: THO 
TEX : THREE 
I EXIWPZ 
7x1 


&>TYPE IIIR.PRN 


@: 
FILENOME TEX : FRONT 
TEX 8 FRONT 
MIK : ONE 
MIK : THREE 
TEX 


1: FOUR 
TEX : ONE 
TEY I L I N E D I T 
TEX I EXRIIPI 
TXT : TYO 
D l K 


1: THO 
TLX : THREE 
MRK I EX4nP2 
TXT 


You can use a similar PUT command to direct printer output to a disk file as well 
as the printer. 


A GET command can direa CP/M 3 or a program to read a disk file for console 
input instead of the keyboard. If the file is to be read by CP/M 3, rt must contam 
standard CP/M 3 mmmand lines. If the file is to be read by a utility program, it must 
contam input appropriate for that program. A file can contain both CP/M 3 com- 
mand lines and program input if it also includes a command to stan a program. 


You add or omit the SYSTEM option in the GET command line to specify whether 


CP/M 3 or a utilitv oroeram is to stan readm~ the file. as shown m the followine 
, . w 


s=rnplr ,rr,lun 
It you omnt the SYSTEhl optno;, 
rhc syircm prompt returns ro tha; 


you can mlrlsrr the progam ~har Br to take tnpur from the rpccnfied file If you 
lnciudr the SY5TFM opr~on. CPlht 3 jmmcd~atcly raker t n y r from the rpcclficd Clc. 


G l t t l n l c o n r o l e l n r v t from t l l r : P1P.ODT 
,4>r,r 


C P l N 3 P I P VERSION 3.0 
.b,=,ront.t,x 


L I Z FILENDNE TEX : FRONT 
TEX : FRONT 
B I K : ONE 
8I)X 
8 THREE 
TEX 
4 : FOUR 
TEX : ONE 
TEX I L I N E D 1 7 
TEX : EXDNPI 
TXT : THO 
141: 


D: TWO 
TEX : EXDNP3 
: EXIMPZ 
TXT 8 
P l l 
0 1 1 : EXAIIPI 


D: THREE 
I R K 
8 EXANPS 
3 CEP 
0 4 7 


See the descriptions of GET and PUT in Section 5 for more ways to use redirected 
input and output. 
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3.5 Assigning Logical Devices 


Most CP/M 3 computer systems have a traditional console with a keyboard and 
screen daplay. Many also have letter-qualiry printers. If you use your computer for 
unusual tasks, you might want to add a different kind of character dcvlu to your 
system: a hne pnnter, a teletypc termmal, a modem, or even a joystick for playing 
games. To keep track of there physically different input and output devices, CP/M 3 
associates dlffercnt physical devlus wlth log~cal devices. Table 3-3 gwes the names 
of CP/M 3 logical devices. It also shows the physical devices assigned to there logical 
devices in the distributed CP/M 3 system. 


CONOUT: 
Console output 
Screen 


AUXIN: 
Auxiliary input 
Null 


Table 3-3. CP/M 3 Logical Devices 


I 
AUXOUT: 
Auxiliary output 
Null 


LST: 
List output 
Printer 


Physical Device 
Assignment 
Logical 
Device Name 


In some implementations of CP/M 3, you can change these assignments with a 
DEVICE command. If your system supports the DEVICE command, you can, for 
example, asslgn AUXIN and AUXOUT to a modem so that your computer can 
communicate with others over the telephone. 


CONIN: 
Console input 
Keyboard 


Devtce Type 


End of Sectton 3 
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Section 4 
CP/M 3 Command Concepts 


As we discussed m Section 1, a CP/M 3 command hne consists of a command 
- keyword, an optional command tail, and a carriage return keystroke. This sealon 


descrtbes the two kinds of oroerams the command kevword can identlhr. and tells 
. - 


how CP/M 3 searches for a program file on a disk. This section also tells how to 
- execute multiple CP/M 3 commands, and how to reset the disk system. 


4.1 Two Kinds of Commands 


A mmmand keyword identifies a program that resides ather m memory as pan of 


CP/M 3, or on a d~sk as a program file. Commands that identify programs in mem- 
ory are called built-m commands. Commands that ldenufy program files on a disk 
are called transient utility commands. 


CP/M 3 has six built-m commands and over twenty transient utility commands. 
You can add utilities to your system by purchasing various CP/M 3-compatible appli- 
cation programs. If you are an experienced programmer, you can also write your 
own utilities that operate with CP/M 3. 


4.2 Built-in Commands 


Built-m commands are pan of CP/M 3 and are always available for your use 


regardless of which disk you have in which drive. Built-in commands reside in mem- 
ory as a pan of CP/M 3 and therefore execute more qutckly than the transient 
utilities. 


Some built-in commands have options that rcqutre support from a related transient 
utility. The related translent has the same name as the built-in and has a filetype of 
COM. This ryne of transient utility is loaded only when a budt-ln command line 
contarns opttons that cannot bc performed by the built-in command 


4.1 Built-in Commurda 
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If you include certain options m the command tail for a built-in command, 


CP/M 3 might return a .CUM Resul red message. ?his means that the command 
tail options require support from a related transient utility and CP/M 3 could not 
find that program file. The following files must be acccss~ble m support all the 
functions these built-ms offer: ERASE.COM, RENAME.COM, TYPE.COM, and 
DIR.COM. 


Section 5 uplains in detail the built-in commands listed in Table 4-1. 


Table 4-1. Built-in Commands 


I Command I 
Function 
1 


DIR 
Displays filenames of all files in the dirmoly u a p t those marked 
with the SYS attribute. 


DIRSYS 
Displays filenames of files marked with the SYS (system) attri- 
butt ~n the directory. 


ERASE 
Erases a filename from the disk directory and release the stor- 
age space occupied by the file. 


RENAME 
Renames a disk file. 


TYPE 
Displays contents of an ASCII (TEXT) file at your screen. 


USER 
Chanees to a dlffemnr user number. 


CP/M 3 allows you to abbreviate the built-in commands as follows: 
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4.3 Transient Utility Commands 


When you enter a command keyword that identifier a transient utility, CP/M 3 
loads the program file from the dirk and passer it any filenames, data, or parameters 
you entered in the command tail. Section 5 provrdcs rhe operating details far the 
CP/M 3 translent utilities listed in Table 4-2. 


1 DATE 
Sen or displays the date and time 


Table 4-2. Transient Utility Commands 


DEVICE 
Assigns logical CP/M devices to one or more physical devices, 
changes device driver protocol and baud rater, or sets consol. 
screen sire. 


DUMP 
Displays a file in ASCII and hexadecimal format. 


ED 
Creates and alters character files. 


Name 


GET 
Temporarily gem console input from a disk file rather than the 
keyboard. 


Dnsplayr information on how to use CP/M 3 commands. 


Function 


1 HEXCOM 
Uses the output from MAC to ~roduce a program file 


COPYSYS 
Creates a new boot disk. 


/ INITDIR 
lnrtialires a disk directory to allow time and date stamping. 


I LINK 


L i d s W (relocatable) program modules ~mduced by RMAC" 
(relocatable macro assembler) and produces program filer. 


I MAC 
Translates assembly language programs into machme mde form. 


PIP 
Copies files and combines files. 
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SETDEF 
1 


1 SUBMIT 


1 
Function 
Temporarily direns printer or console output to a disk file. 


Tanslates assembly language programs into relocatable pro- 
gram modules. 


Sets file optrons including disk labels, file attributes, type of 
time and date stampnng, and password protenion. 


Sets system options including the drive search chain. 
I 
Displays disk and drive statistics. 
I 


Helps you check your programs and interactively correct pro- 
grammlng errors. 


Automat~cally executes multiple commands. 
I 
Producer a cross-reference list of variables used in an assembler 
program. 


4.4 How CP/M 3 Searches for Program and Data Files 
- 


This section describes how CP/M 3 searches for program and data fils on disk. If 
it appears that CP/M 3 cannot find a program file you specified in a command line, - 
the problem might be that CP/M 3 a nor looking on the drive where the file is 
stored. Therefore, you need to understand the steps CP/M 3 follows in searchtng for 
program and data files. 
- 


4.4.1 
Finding Data Files 


As you recall, when you mtcr a command Ime, CP/M 3 passes the command tail - 


to the program identified by the command keyword. If the command tail contains a 
filc specification, the program calls CP/M 3 to search for the data file. If CP/M 3 
cannot find the data~filk the program displays an error message at the console. 
Typically, thw message is Fi le n o t f o u n d or No File, but the message depends - 


on the program ~denrified by the command keyword. 
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- 
If you do not indudc a drivc specifier with the filename in a mmmand tad, 


CP/M 3 searcher the directory of the cumnt user number on the default drive. If the 
file is not there, CP/M 3 lwks for the file with the SYS attribute in the directory of 
user 0 on the default drive. If CP/M 3 finds the file under user 0, it allows the 
- program Read-Only access to the file. For example, if you enter the followtng com- 
mand line, 


CP/M 3 first searches the directory for uscr 3 on drive A. If it does not find 
MYFILE.TXT there, it searches the directory of user 0 on drive A for MYFILE.TXT 
- marked with the SYS attribute. If the filc is not in cnhcr directory, CP/M 3 returns 


control to TYPE, which then displays No F i 1 e. 
- 
Some CP/M 3 unlitles, such as PIP and DIR, restrict their filc search to the current 


uscr number. Because CP/M 3 does not allow Read-Write access to SYS files;ERASE 
and RENAME also restrict their search to the current user number. 


The search procedure is basically the same if you do indudc a drive specifier with 


the filename. CP/M 3 first lwks in the directory of the current user number on the 
specified drive. Then, if it does not find the file, it looks m the directory for user 0 
on the specified drive for the file with the SYS amibute. If CP/M 3 does not find the 
data file aker these two searcher, it displays an ermr message. 


4.4.2 
Finding Program Files 


The search procedure for a program file can be very different fmm a data file 
search. Thls is because you can use the SETDEF command described in Section 5 to 
define the search procedure you want CPlM 3 to follow when it is look~ng for a 
p m p m file. With SETDEF you can a t CP/M 3 to make as many as s 
h 
searches 


when you do not include a drivc specifier before the command keyword, but that is 
a rare case! We will begin by describing how CP/M 3 searches for program files 
whm you have not yet entered a SETDEF command. 


If a command keyword identifies a transient utility, CP/M 3 looks for that program 
file on the default or specified drive. It lwks under the current uscr number, and 
then under user 0 for the same file marked with the SYS attribute. At any point in 
the search proaas, CP/M 3 stops the search if it finds the program file. CP/M 3 then 
loads the program into memory and executes it. When the program terminates, 
CP/M 3 displays the a p c m pmmpr and waits for your next command. However, 11 
CPlM 3 does not find the command file, it repcats the command line followed by a 
question mark, and waits for your n u t command. 
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If you indude a drive specifier before the command keyword, you are telling 


CP/M 3 preci~ly where to look for the program file. Therefom, CP/M 3 searches 
only two locations: the dlrectoq for the current user on the specified dnvc, and then 
for user 0 on the specified drivc, before it repeats the command line with a question 
mark. For example, ~f you mter 


CP/M 3 Iwks on drive A, user 4 and thm user 0 for the file SHOW.COM. 


If you do not include a drwc specifier before the command keyword, CP/M 3 
searches dlrcctories in a sequence called a drive chain. When you Lst receive 
CP/M 3, them is only one drive in your cham, the default drive. Unlerr you change 
the chain with a SETDEF command, CP/M 3 looks in two places for the program 
file. For uample, if you enter 


CP/M 3 searches the following locations for the file SHOW.COM: 


1. drive E, user 7 
2. drive E, user 0 


Remember that a SHOW.COM file under user 0 must be marked with the SYS 
artrmbute or cl,c CP 51 3 cannot find Ir Uw a SET command to pvr program filer 
under u5cr 0 ro the SYS amrburr hccaure they can then be a~crrrrd automar~cally 
from all other user amas You do nut have t o dupllcatc frcqurnrly urcd program filer 
in all UMI areas on all drives. 


Whrn you use a SETDEF command to define your own drive chain, indudc the 


default drive, and the drive that contains your most frequently used utilities. For an 
example, assume you defined your drtvc cham as ' (the default drivc) and drivc A. 
When you enter the following command: 
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CP/M 3 looks for SHOW.COM in the following sequence: 


1. drive D, user 2 
2. drive D, user 0 
3. drive A, user 2 
4. drive A, user 0 


You can indudc your default drive in your drive chain wlth an option in a SETDEF 
command. Any drive chain you specify with SETDEF remains in effect until you 
restan or reset the system. 


You can also use a SETDEF command to enable automatic submlt in your drive 
chain. See Section 4.5 for a description of automatic submit. 


4.5 Executing Multiple Commands 


In the examples so far, CP/M 3 has executed only one command at a tnme. 


CP/M 3 can also execute a sequence of commands. You can enter a sequence of 
commands at the system prompt, or you can put a frequently needed sequence of 
commands m a disk file. Once you have stored the sequence ~n a disk file, you can 
execute the sequence whenever you need to with a SUBMIT command. 


To enter multiple commands at the system prompt, separate each command key- 
word and associated mmmand tail from the next keyword with an exclamation 
point, !. When you complete the sequence, press RETURN. CP/M 3 executes your 
commands in order 


3 I > d l r r r l ' d l r #xalrt.rlshor I l n c , l 
NON-SYSTEM FILE151 EXIST 
3 l > d l r #xa#r*.. 
I: EXInP7 
I EXIIIPL 
TXT : EXIMP3 
: EXIMPZ 
TXT : EXIMPP 


l i EXIMPS 
: EXAIPB 


I P > , h O " 
Il..".l 


I : R Y t S*ac.: 
3 t 3 4 4 l 
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If you find you need to w m t c the same command sequence frequently, store the 


sequence m a disk file. To create this file, use ED or another character file editor. 
The file must have a filetype of SUB. Each command in the file must start on a new 
line. For example, an UPDATESUB file might look like this: 


DIR Rz*.COM 
ERR B:r.COM 
PIP B:=R:*.COM 


To execute this hst, mter the following command: 


The SUBMIT utility passes each command to CP/M 3 for sequential wecution. While 
SUBMIT executes, the commands arc usually echoed at the console, as well as any 
program's screen display, ruch as the directory or PIP'S "COPYING..." message. 
When one command completes, the system prompt reappears either with the next 
command in the SUB file, or, when the SUB file is exhausted, by ltself to wait for 
your next command from the keyboard. 


If PROFILE exists, PROFILE.SUB is a special submit file that CP/M 3 aummati- 


cally w m n s at each cold start. This feature rs especially convenient if you regularly 
wecutc a standard set of commands. ruch as SETDEF and DATE SET. before bmn- 
ning a work session. A PROFILE.SL~ might already exist on your dlskburion &k. 
If not, you can create one using ED or another editor. 
- 


The description of the SUBMIT utility in Section 5 gives more details on how to 


create a SUB file and use SUBMIT parameters to pass options to the programs to be 
executed. 
- 


You can also use CTRL-C to reset the disk system. This is sometimes called a 


warm start. When you press CTRL-C and the cursor is at the system prompt, - 
CP/M 3 logs out all the active drives, then logs in the default drive. The active drives 
are any dives you have a-cd 
since the last cold or warm nart. A SHOW [SPACE] 
command displays the remaining space on all active drives. In the following example, 
SHOW [SPACE] indicates that thre drives arc active. However, if you press CTRL-C - 


immcdiatcly afrn this display and chm mtcr anothcr SHOW [SPACE] command, only 
the space for the default drive, A, is displayed. 
- 


4.6 Terminating Programs 


You can use the two keystroke command CTRL-C to termmate program execution 
or reset the dlsk system. To enter a CTRL-C command, hold down the CTRL key 
and press C. 


Not all application programs thar run under CP/M can be termmated by a 
CTRL-C. However, mosr of the transient uttlit~es suppl~cd with CP/M 3 can be 
terminated immediately by a CTRL-C keystroke. If you try to terminate a program 
while it is scndlng a display to the screen, you might need to press a CTRL-S to halt 
the display before enrcrlng CTRL-C. 


You can also use CTRL-C to reset the disk system. This e sometimes called a 
warm stan. When you press CTRL-C and the cursor is at the system prompt, 
CP/M 3 logs out all the actwe drives, then logs in the default drive. The active driver 
are any drives you have accessed since the last mld or warm scan. A SHOW [SPACE] 
command displays the remaining space on all active dnves. In the following exam- 
ple, SHOW [SPACE] lndlcarcs thar t h e drives arc amve. However, if you press 
CTRL-C immediately after this display and then enter anorher SHOW [SPACE] 
command, only the space for the default dnve, A, is daplayed. 


A>SHDW [SPACE1 
A: RW, 
Space: 
9 . 4 8 8 8 


8: R O , 
S p a c e : 
2 , 4 5 4 8 


C : R O , 
S p a c e : 
1 ~ 6 6 5 8 


A > ^ C 
&>SHOW CSPACEI 
A: 
R U . 
SP~EI: 
9 , 4 8 8 1 


4.7 Getting Help 


CP/M 3 includes a transient utility command called HELP that can display a 
summary of what you need to know to use each command described ~n this manual. 
To get help, simply enter the command: 
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In response, the HELP utility dlrplays a list of topics for which summaries arc 
available. Aker HELP lire the topics avadable, it displays its own prompt: 


HELP> 


To this prompt, you can enter one of the topia presented in the list, for example, 


HELP>SHOW 


Aker displaying a summary of the SHOW command, HELP lists subtoplcs that detail 
d~ffercnt aspects of the SHOW command. To display the information on a rubmpic 
when vou have iusr fintshcd rcadlne the main toolc. enter the name of the rubtooic 


HELP). OPTIONS 


In the preceding example, HELP then displays the options available for the SHOW 
command. As you become famihar with HELP, you might want to call a HELP 
subtopic directly &om the system prompt as follows: 


A>HELP SHOW OPTXONS 


HELP lets you learn the basic CP/M 3 commands quickly. You might find that 
you reference the command summary in Sectson 5 only when you need details not 
provided ~n the HELP summaries. When you add new utihues, you can modify HELP 
ro add or subtract toptcs, or wen modify the summaries HELP presents. See the 
description of HELP in Section 5 for complete details. 


End of Secnon 4 
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Section 5 
Command Summary 


This wctlon describes the commands and programs supplied with your CP/M 3 
operating system. The commands are in alphabetical order. Each command is fol- 
lowed by a short explanation of Its operation and examples. More complicated com- 
mands are described later in detail. For example, ED is described in Section 6. Other 
commands, such as SID and MAC, arc described fully in other CP/M manuals. 


CP/M 3 has replaced some commands h m prwlous CP/M vcnlons. MAC q l a a r 


ASM; SHOW and DIR include the previous STAT functions; and SID replaces DDT. 


5.1 Let's Get Past the Formalities 


This section describes the pans of a file specification in a command line. There are 
four pans in a file specification; to avoid confusion, each part has a formal name: 


drive rpccificr-the 
optional disk drive A, B, C, ... P that contains the file or 
group of files to which you are referring. If a drive specifier rs tnduded in 
your command line, a colon must follow it. 


1 filcname-the one- to eight-character first name of a file or group of files. 


fi-the 
optional one to three-character category name of a file or group 
of files. If the filetype is present, a period must separate it Itom the filename. 
password-the opt~onal one- to cight-character password which allows you 
to protect your files. It follows the filcrypc, or the filename if no filetype is 
assigned, and is preceded by a semicolon. 


If you do not include a drive specifier, CP/M 3 automatically uses the default drive. 
If you omit the period and the filetype, CP/M 3 automatically includes a filetype of 
t h m blanks. 


5.1 Let's Get Pasf the Pomdititi 
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This general form is called a file specificat>on. A file specificanon names a parucu- 


lar file or group of files in the directory of the on-hne disk given by the drive 
specifier. For example, 


is a file specification that indicates drive B:, filename MYFILE, and filetype DAT. File 
specificatton is abbreviated to 


filespec 


in the command syntax statements. 


Some CP/M 3 commands accept wildcards in the filename and filetype parts of the 
command tail. For example, 


is a file specification with drive specifier B:, filename MY*, and filetype A??. This 
amb~guous file specification might match several files in the directory. 


Put together, the parts of a file spectfication are represented like tha: 


In the preceding form, d: represents the optional drive specifier, filename represents 
the one- to eight-character filename, and typ represents the optional onc- to three- 
character filetype. The syntax descriptions in this section use the term filespec to 
~ndccare any valid combination of the elements included in the file speclcation. The 
following list shows valid combinations of the elements of a CP/M 3 file specification. 


I filename 


filenamc.typ 


1 filename;password 


filcname.typ;password 
I d:filename 
m d:filename.typ 
B d:filenamc;password 
B d:filenamc.ryp;password 
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The characters in Table 5-1 have rpeclal meaning in CP/M 3, ao do not use these 
characters m file spocification~ u a p t as indicated. 


Table 5-1. 
Reserved Characters 


Chorann 
I 
Meoning 


< = , ! I > [ ] 
file specification delimiters 


tab space 
carrlage return 


I : 


drive delimiter in file specification 


I 
filetype delimiter in file specification 


I ; 
password delimiter m file specification 


I 
' ? 
wildcard characters in an ambrguous file spccrfication 


1 ; 
> .4 
1 1 H - 
option list delimiten 


option list delimiters for global and local options 


delimiters for multiple modifiers lnside square brackets 
for options that have modifiers 


option delimiters in a command line 


comment delimiter at the beginning of a command line 
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CP/M 3 has already established several file groups. Table 5-2 lists some of their 


filerypcs wtth a short description of each famdy. Appendix C provides the complete 


Assembler source file 


CBASIC. source program 
1 
8080, 0 8 5 or equivdent machine Iangw- 
program 
1 


HELP message file 


Llst of commands to be executed by SUBMIT 


Temporary file 


In some commands, descriptive qualifiers are used with filespecs to further qualify 


the rypc of frlespcc accepted by the commands. For example, wildcard-filespec denotes 
wildcard rpecifications, dest-filespec denotes a destination filespec, and src-filespec 
denotes a source filespec 


You now understand command keywords, command tails, control characters, default 


dnve, and wddcardr. You also see how to use the formal names filespec, drwe 
specder, filename, and filetype. These concepts give you the background necessary to 
compose complete command liner. 


5.2 How Commands Are Described 


CP/M 3 commands appear in alphabetical order. Each command description is 


given m a specific form. Ths sectzon also describes the notation that indicates the 
optional pam of a command hne and other syntax notatlo". 


m The description begins with the command keyword in upper-case. 


m The syntax section gives you one or more general forms to follow when you 
compose the command Imc. 
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The explanation section definer the general use of the command keyword, 
and polnts out exaptions and specla1 cases. The explananon sometimes 
includes tables or list. of options that you can use in the mrnmmd Ime. 


I We examples section lists a number of valid command liner that use the 
command keyword. To clanfy examples of interactions bcnvecn you and the 
operating system, the characters that you enter are slanted. The responses 
that CP/M 3 shows on your screen arc in vertical type. 


The notation in the syntax llncs describes the general mmmsnd form urtng these 


~ C E : 


m Words in capital lmns must be spelled as shown, but you can use any 
combination of upper- or lower-case letters. 
I The symbolic notation d:, filename, .typ, ;password, and filespec have the 
general meanings descrzbcd m Section 5.1. 
I You must indude one or mare space characters where a space 1s shown, 


unlas otherwise speclficd. For example, the PIP options do not need to be 
separated by spaces. 


The following table defines the special symbols and abbreviations u ~ d 
in syntax 


hnes. 


Table 5.3. 
Syntax Notation 


Symbol 
I 
Meontng 


DIR 
Directory attribute. 


You can subsntute a number for n. 


Indicates an option or an option list. 


RO 
Read-only. 


RW 
Read-Write. 


5 
You can substitute a string, which consists of a group of 
charactezs, for r. 


- 
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Table 5.3. 
(wntinucd) 


Symbol 
I 
Mcanmng 


SYS 
System attribute. 


ltems within braces are optional. You can enter a command 
without the opt~onal items. The optional itthr add effects to 
your command line. 


Items m square brackets are options or an option list. If you 
use an option specified w~thin the bracken, you must type the 
bracken to enclose the opnon. If the right bracket is the last 
character on the command line, it can be omitted. 
I 


Items m parentheses indicate a range of options. If you use a 
range from an option list, you must endose the range in 
parentheses. 


Ellipses tell you that the previous item can be repeated any 
number of tunes. 


I 
The or bar separates alternative items in a command hne. 
You can sclm any or all of the alnrnariva spenficd. Mutually 
exclusive options are indicated ~n additional syntax liner or 
are specifically noted in the text. 


1 
a CI'RL 
Represent the CTRL key a your keyboard. (CTRL charac- 
ters show as an your screen.) 


Indicates a carriage return keystroke. 
I 
Wildcard character-replaces all or part of 1 filename andlor 
filetype. 


Wddcard character-replaces any single character in the same 
oosltion of a filename or fileome. 
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Let's look at some examples of syntax notatlon. The CP/M 3 DIR (DIRectory) 


command displsys the names of files cataloged m the disk directory and, optionally, 
displays other information about the files. 


We syntax of the DIR command with options shows how to use the command 
line syntax notation: 


Syntax: 
DIR{d:)l{filespec}{[options1) 


I 
I 
I 


optlonal optlonal optlonal 


This tells you that the mmmand rail follo~ng the mmmand w o r d DIR b optional. 
DIR alone is a valid command, but you can indude a file speclfication, or a drive 
specification, or just the options in the command line. Therefore, 


DIR 
DIR filespec 
DIR d: 
DIR [RO] 


are vahd commands. Furthermore, the drive or file specificatron can be followed by 
another optional value selected from one of the following list of DIR options: 


RO 
RW 
D1R 
SYS 


Therefore, 


DIR d:filespec [RO] 


is a valid command 


Recall that in Section 2 you learned about wildcards in filenames and filetypes. 


The DIR command accepts wildcards in the file speclfication. 
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Usmg thls syntax, you can construct several valid command lines: 


DIR 
DIR X.PAS 
DIR X.PAS [RO] 
DIR X.PAS [SYS] 
DIR *.PAS 
DIR '.* [RWI 
DIR X.' [DIR] 


Ihe CP/M 3 command PIP (Peripheral Interchange Program) is the file copy pro- 
gram. PIP can copy miormation from the disk to the screen or printer. PIP can 
combine ouo or more files tnto one longer file. PIP can also rename files aher copying 
them. Look at one of the formats of the PIP command linc for another example of 
how to use command linc notation. PIP also coples files from one disk to another 
disk. 


Syntax: PIP dest-filespec= src-fiIespec(,fiIespeccC.) 


In the preceding example, dest-filespec e further defined as a destination file speci- 
fication or peripheral device (printer, for example) thar receives data. Slmtlarly, src- 
filespec is a source file specification or peripheral device (keyboard, for example) that 
transmits data. PIP accepts wlldcards in the filename and filetype. (See the PIP com- 
mand for details regarding other capabil~ties of PIP.) There are, of course, many valid 
command lines thar come from thls syntax. Some examples follow. 


P I P NEUFILE.DAT=OLDFILE.OAT 
P I P B:=R:THISFILE.DRT 
P I P B:X.BAS=Y.BAS# 
ZIBAS 


P I P X + B A S = A I B A S ~ B.BASt 
C.BAS 


P I P B:=A:+.BAK 
P I P B:=R:*.* 


The remainder of this seaion contains a complete descnptlon of each CP/M 3 utilmq. 
The descriptions arc arranged alphabetically for easy reference. 
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The COPYSYS Command 


Syntax: 
COPYSYS 


Explanation: The COPYSYS command copies the CP/M 3 system from a CP/M 3 
system disk to another dirk. The disk murt have the same format as 
the orlgnal system disk. For example, if the system drsk is a single- 
density disk, the disk you use to copy onto must also be in single- 
density format. 


The COPYSYS utility copies only the system tracks onro the new disk. 
To use the new disk as a CP/M 3 SyStFm disk, you murt also c ~ p y 
rhe 


system file CPM3.SYS to the new disk. COPYSYS gives you the option 
to copy CPM3.SYS to the new dirk. To copy other files onro the new 
disk, use the PIP command. 


emrnpl=: n,copvsvs 


C o ~ u s u s 
Ver 3.0 


S o u r e e d r i v e nare ( o r r e t u r n f o r d e f a u 1 t ) C 
S o u r c e on C t h e n t r e e r e t u r n 


Place the disk to be copied in drive C, then enter <a>. 


F u n c t i o n C o m ~ l e t e 
~ 
- - 
- - - 


D e s t i n a t i o n d r i v e name ( o r r e t u r n t o r e b o o t ) [ : 
D e s t i n a t i o n on C t h e n ~ V P L 
r e t u r n 


Replace the system dirk in C with the new disk, then enter <cr> 


F u n o t l o n o o m ~ l e t e 
Do y o u u i s h t o e o ~ u 
CPM3.SYS9Y 


S o u r c e d r i v e name ( o r r e t u r n f o r d e f a u l t ) < c r > 
S o u r c e o n d e f a u l t t h e n t y p e r e t u r n 
F u n c t i o n c o n ~ l e t c 
D e s t i n a t i o n d r i v e nare ( o r r e t u r n t o r e b o o t ) [ : 
D e s t i n a t i o n on C t h e n t r e e r e t u r n 
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Place the dlsk to be copied m drive C then enter <a>. 


The preceding example copies the CP/M 3 system using only one disk 
drive C. In the preceding messages, the word source refers to the dek 
that contatns the CP/M 3 system, and the word destination refers to 
the disk to which the CP/M 3 system is to be copied 


The system file CPM3.SYS is copled from the default drive A to the 
new disk in drive C. CP/M 3 requires the file CPM3.SYS to be an the 
system disk. 


- 
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- The DATE Command 


Syntax: 
DATE {CONTINUOUS} 
- 
DATE {time-specification) 
DATE SET 


Eqhaation: The DATE command is a transient uulity that lets you display m d scr 
- 
the date and time of day. When you stan CP/M 3, the date and time 
are set to the creatnon datc of your CPlM 3 system. Use DATE to 
change this initial value to the current date and rime. 


Display Current Date and Time 
- Syntax: 
DATE {CONnNUOUS} 


Lxplananon: The prcccdlng form of the DATE command dmrplayr the currrnr date 
- 
and r~me. Thc CO.NllNUOU\ oprlon allows cunt~nuour d~rplay of thc 
dare and rlmc. The COhTlNUOUS oprnon can be abbrcvt~rcd tu (1. 
You can stop the continuous drsplay by pressing any key 
- Examples: 
A > Do TE 
A>DdTEC 


The first example displays the c u m t date and time. A sample display 
might be: 


The second example daplays the datc and time continuously until you 
- 
press any key to stop the display. 


Set the Date and Time 
- 


Synrax: 
DATE {time-spec$fication) 
DATE SET 
- 
- 
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Elrplmadon: The first form allows the user to enter both datc and rime in the com- 
mand. The time-specification format is 


MMiDDPIY HH:MM:SS 


where: 


MM is a month value in the range 1 to 12. 
DD is a day value in the range 1 to 31. 
W is the two-dlgit year value relative to 1900. 
HH is the hour value in the range of 0 to 23. 
MM is the minute value in the range of 0 to 59. 
SS is the second value in the range of 0 to 59. 


The system checks the validity of the datc and time entry and deter- 
mines the day for the date entered. 


The second form prompts you to enter the date and the timc. To keep 
the current system date or time, press the carriage refurn. 


The system responds with 


P r e s s a n y LLI t o s e t ti.. 


Whm the time occurs, press any key. DATE initializes the rime at that 
instant, and displays the date and timc: 
- 


S a t 0 8 1 1 4 1 8 2 1 0 : 3 0 : 0 0 


&>DATE SET 


The system prompts with 


E n t e r t 0 d a ~ ' s 
d a t c (PlMlDDIYY): 


- 


DIGITAL RESEARCH- 


5-12 


CP/M 3 User'* Guide 
The DAl€ Command 


Press the carriage return m skip or enter thc dace. Then thc system 
prompts w~th 


E n t e r t h e t i m e (HH:MM:SS): 


Press the carriage mum to skip or mru the time and the system promprr 
with 


P r e s s an* I L I ~ O 
s e t time 


to allow you to set the time exactly. 


The DEVlCE Command 


The DEVICE Command 
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Syntax: 
DEVICE {NAMES I VALUES I physical-dev I logical-devl 
DEVICE loeical-dn = ~hvsical-dev {oution) 


i,;hyscal-dev 
Iopnon), ... ) 


DEVICE logical-dev = NULL 
DEVICE physical-dev {optton) 
DEVICE CONSOLE [PAGE I COLUMNS = columns I LINES =lmes) 


Explanation: The DEVICE command is a transient utility that displays current 


assignments of CP/M 3 logical devices and the namcs of physical devices. 
DEVICE allows you to asslgn logical CP/M 3 devices to peripheral 
devices anached to the computer. The DEVICE command also sen the 
communications protocol and sped of a peripheral device, and da- 
plays or sns the current console screen size. 


CP/M 3 suppons the following five logical devices: 


CONIN: 
CONOUT: 
AUXIN: 
AUXOLT: 
LST: 


These logical devices are also known by the following names: 


CON: (for CONIN: and CONOUT:) 
CONSOLE:-(for C O G N : - ~ ~ ~ 
CONOW) 


KEYBOARD (for CONIN:) 
AUX: (for AUXIN: and AUXOLT:) 
AUXILIARY: (for AUXIN: and AUX0LT:I 
PRINTER (for LST:) 


The physical device namcs on a computer vary from system to system. 
You can use the DEVICE command to display the names and attributes - 
of the physical devices that your system accepts. 


- 


O DIGITAL RESEARCH" 
5-14 


Display Device Characteristics and Assignments 


Synmx: 
DEVICE ( NAMES I VALUES I phyrical-dev I logical-dcv) 


Explanation: The preceding form of the DEVICE command displays tho nama and 


aturburcs of the physical devices and the current assignments of the 
logical devices ~n the systcm. 


The preccdrng command displays the physical devices end current 
assignments of the logical devices in the system. The following is a 
sample response: 


P h r n c a l O e u l r e r r 


l = l n r u t , O r o u t . U I . S = E . r l a l ~ x = X l l n - x D r f 


CRT 
9 5 0 0 
1 0 5 
L P l 
5 9 0 0 
10SX 
C R l l 
9 5 0 0 
1 0 5 


CRTZ 
9 8 0 0 
1 0 5 
CRT3 
4BOO 
1 0 5 
L P T l 
1 3 4 
IOSX 


CEN 
NONE 
0 
MODEM1 1 5 2 0 0 1 0 9 
MODEM2 3 0 0 
5 


CTRLRI I S 0 
0 
CRlCRT 1 9 2 0 0 1 0 5 
D I l l l L O 1 1 0 
0 


CTRLRZ 3 0 0 
0 
S C R l l 
7 2 0 0 


C U I I I ~ ~ L I I I L ' " . ~ " ~ . ~ 


CONIN: . 
CRT 


CONOUli = CRT 


W X I I I : . 
N u l l D e u l c l 


PUXOUTt = N u l l O l u r o ~ 


Ls,: 
. 
LPT 


The systcm prompts for a new device assignment. You can enter any 
valid device asstgnment (as described m the next smion). If you do not 
want to change any device assignments, press the RETURN key. 


A>DEVICENAMES 


The preceding command lists the physical devices with a summary of 
the device characterisria. 


DIGITAL RESEARCH'" 


5.15 


The DEVICE Command 
CP/M 3 Usdr Guide - 


A > D E V I C E VALUES 
- 


The prmding mmmand displays the ~ m n t 
logical dwbx as~pmmm. 


A > D E V I C E C R T 
- 


The preceding command displays the attributes of the physical device 
CRT. 
- 


The preceding command displays the assignment of the logxcal device 
CON: 


Assign a Logical Device 


Syntax: 
DEVICE logical-dev = physical-dev {option) 


[,physical-dw [option),..> 


DEVICE logical-dev = NULL 


Explanation: The first form assigns a logical device to one or more physical dwiccs. 


The wand form discomem the logical dwice from any phys~cal devlce. 
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XON 
refers to the XONKOFF communications protocol. 
This pmtoml uses two spedal characten in the ASCII 
character set called XON and XOFF. XON signals 
transmission on, and XOFF signals transmission off. 
Before each character is output from the computer to 
the peripheral device, the computer checks to see if 
there is any incoming data from the peripheral. If the 
incoming character e XOFF, the computer suspends 
all further output until it receives an XON from the 
device, ~ndicating that the device is agaln ready to 
receive more data. 


Table 5 4 . DEVICE Options 


NOXON 
indicates no protocol and the computer sends data to 
the device whether or not the device is ready m rmive 
It. 


baud-rate 
is the speed of the device. The system accepts the 
following baud rater: 


Option 


Examples: 
& > D E V I C E CONOUT: =LPT,CRT 
& > D E V I C E W J X I N : = C R T Z CXON,9SOOl 
& > D E V I C E LST:=NULL 


Meaning 


The first example assign* the system conrolc output, CONOUT:, to the 
printer, LPT, and the succn, CRT. The second example assigns the 
auxtllary logical mput device, AUXIN:, to the physlcal device CRT 
using pmrocol XONKOFF and uo the transmission rate for the device 
at 9600. The third example disconnects the list output logical devtce, 
LST:. 


Set Attributes of a Physical Device 


S p w 
DEVICE physical-dev {option) 


Explannuon: The preceding form of the DEVICE command sets the attributes of the 
physical device specified in the command. 


Example: 
A > D E V I C E L P T CXON,96001 


The preceding command sets the XONKOFF promcol for the physrcal 
device LFT a d x t s the transmission speed at 9600. 


Display or Set the Current Console Screen Size 


S p w 
DEVICE CONSOLE [PAGE ( COLUMNS=columns I LlNFS=lines] 


Expl~n~tion: 
The preceding form of the DEVICE command displays or sets the cur- 
rent console sire. 


Exunplcr: 
R>DEVICE CONSOLE I P A G E I 
A>DEVICECONSOLECCOLUPINS=4Oo L I N E S = 1 6 1 


The finr example displays the current mnrolc page width in columns 
and length in line. The second example sets the rcmm size to 40 
columns and 16 liner. 


- 


m DIGITAL RL5LbRCHTI 


5-18 
- 


- 
CP/M 3 User's Guide 
The DIR Commnnd 


- The DIR Command 


Syntax: 
DIR {d:) 
- 
DIR {filespec) 


DlRSYS {d:) 
- 
DIRSYS (filespec) 


DIR {d:) [options] 
DIR {filespec) {filcspcc) ... [options] 
- 


Explanatiom The DIR command displays the names of files and the attributes asso- 


clated with the filer. DIR and DIRSYS are built-in utilities; DIR wlth 
- 
options is a transient utlltcl. 


Display Directory 
- 


Syntax: 
DIR {d:) 
DIR {filespec) 
- 


DIRSYS {d:) 
DIRSYS {filespec) 
- 
Explananon: 'lhr DIR and DIRSYS commands dlrplay the namrr of filer catalog4 


tn the dlrcctory of an on-llnc dnk. The DIR command l~rrr rhc namrs 
of filer ~n the current user numher that have the U~rnrory (DIR artn- 
bute. DIR accepts wildcards m the file specdcation. You can abbrev~atc 
the DIRSYS command to DIRS. 


The DIRSYS command displays the nama of files in the current user 
number that have the System (SYS) attribute. Although you can read 
System (SYS) files that are stored in user 0 from any other user number 
on the same dnvc, DIRSYS only displays user 0 files if the current user 
number is 0. DIRSYS accepts wildcards in the file specification. 


If you omlr rhc drtvr and filc spccdcanon<, rhc DIR command dsplay\ 
the names of all filer wnh the DIR anrthutc on the default drwc for rhc 
current urcr number Stmmlarly. DIRSY5 dtrplayr all the S Y I filrr 


- 
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If rhc d r ~ c 
spccdrr rr ~n~ludcd, 
bur rhc filrnamr a d filcwc am omrr 


red, the DIR command djrplnyr rhc namcs of 311 DIR files ~n rhc current - 


u r r un thr dtrk 10 the rpccdcd drwc DIRSYS dsplay, rhc SYS filer 


If the file specification contains wildcard characters, all filenames that 
satisfy the march are displayed on the screen. 


If no filenames match the file specification, or if no files are cataloged 
in the directory of the disk in the named drive, the DIR or DIRSYS 
command displays the message: 


No F i l e 


If system (SYS) file match the file spedficadon, DIR displays the message: 


S Y S T E M F I L E ( S ) E X I S T 


If nonsystem (DIR) files match the file specification, DIRSYS displays 
the message: 


NON-SYSTEMFILESIS) E X I S T 


The DIR command pauses aker filling the screen. Press any key to 
continue the daplay. 


Note: 
You can use the DEVICE mmmand to change the number of 
columns displayed by DIR or DIRSYS. 


Examples: 
A > D I R 


Displays all DIR files cataloged in user 0 on the default drtve A. 


A > D I R 8 : 


Displays all DIR files for user 0 on drive B. 
- 


A > D I R B : X . B L S 


Displays the name X.BAS if the file X.BAS is present on drive 8. 
- 
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4 R > D I R * . B 4 S 


Displays all DIR filcs w~th filetype BAS for user 4 on drive A. 


B > D I R A:X*.C?D 


Displays all DIR filcs for user 0 on dnve A whose filename begins with 
the letter X, and whore three character filetype contams the first char- 
acter C and last character D. 


Displays all filcs for user 0 on drive A that have the system (SYS) 
attribute. 


This abbreviated form of the DIRSYS command dlsplayr all SYS files 
with filetype COM on the default drive A for user 3. 


Display Directory with Options 


Syntax: 
DIR {d:) [options] 
DIR {filespec) {filespec) ... [optlons] 


Explanation: The DIR command wlth options is an enhanced version of the DIR 
command. The DIR command dlsplays CP/M 3 files m a variety of 
ways. DIR can search for files on any or all dnvcs, for any or all user 
numbers. 


DIR allows the option list to occur anywhere in the command tarl. 
These options modify the entire command line. Only one option list 1s 
allowed. 


Options must be enclosed in square bradietr. The optlons can be used 
indiv~dually, or s a g togaher separated by mmmas or spaas. Options 
can be abbreviated to only one or two lmen if the abbreviation unam- 
btguously identifies the option. 
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If a directory listing exceeds the stze of your sueen, DIR automatically 
halts the display when it fills the screen. Press any key to continue the - 


display. 
- 


Table 5-5. D m Display Options 


displays files with date and time stamps. If date 
and time stamping is nor actwe, DIR displays the 
mesrage: 
1 - 


Option 
Function 


A n - 


displays the user-definable file anr~butes F1, F2, 
F3, and F4. 


- 


DATE 


1 
D a t e and T i m e S t a m p i n s I n a c t i v e . 
I 


- 
- 
- 


displays files on all accessed drives. DISK 1s also - 
acceptable 1x1 place of DRIVE in all the DRIVE 
options. 


displays only files that have the DIR attribute. 


DRIVE= ALL 


DRIVE=(A,B,C ,..., P) 


displays files on the drives specified. 
1 
^ 


- 


- 
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DRIVE=d 


displays files on the drive specified by d. 


- 
- 


- 
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- 
Table 5-5. (continued) 


- 


displays the files on the default drive and user 
area that do not match the files specified in the 
- 


xnds an ~niual form-feed to the printer device if 
the printer has been activated by CTRL-P. If the 
LENGTH=" option is also specified, DIR issues 
a form-feed every n lines. Otherwise, the FF option 
deactivates the default paged output daplay. 


shows the name of the file and the sire of the file. 
The size is shown as the amount of space in ki- 
lobytes and the number of 128-byte records allo- 
cated to the file. FULL also shows the attributes 
the file. (See the SET command for description of 
file attributes). If there is a directory label on the 
drive, DIR shows the password protection mode 
and the time stamps. The display is alphabetically 
sorted. FULL e the default output format for dis- 
play when using DIR wcth options. 


displays n hnes of output before inserting a table 
heading. n must be in the range between 5 and 
65536. The default length is one full screen of 
in6nrm,rinn 
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Table 5-5. (continued) 


Optron 
Function 
I 
I MESSAGE 
I 


&splays the name of the s@ed 
dnvcs and user 
numbers it is currently searching. If there are no 
files in the specified locations, DIR displays the 
file not found message. 


continuovjly scrolls lnfomation by on the screen. 
Does not wait for you to press a key to restart 


displays files in the order it finds them on the 
disk. If this option is not included, DIR displays 
the files alphabnically. 


displays only the files that have the Read-Only 
attnbutc. 


1 SIZE 
I - 


RW 


displays only the files that are set to Read-Write. 


displays the filename and file sire ~n kilobytes. 


SYS 


- 


displays only the files that have the SYS attribute. 
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Table 5-5. (continued) 


Option 
Function 


USER=ALL 


displays all files under all the user numbers for 
the default drive. 


displays the files under the user number specified 
by n. 


d~splays files under the user numbers specified. 


Examples: 
A > D I R C : rFULLl 
R > D I R C : L S I Z E I 


The following is sample output of the [FULL] option display format 
shown in the first example of the DIR command: 


N I M L 
8 7 t l l 
RICI 
Pttr1buI.s 
P l o t 
Update 
R o c l s r 
. . . . . . . . . -. . . . . . . . . . . . . . . . . . . -. . . . . . . 
- . . . . . . . . . 
- - - - . . . . . . . . . . . . . . . . . . . 


OITS 
D M 
I I 
L DIP 
RY 
RInd 
08/01/82 13:OP 
09/01/82 11:07 


DlTE 
TEE 
1 I 
1 O i r RO 
None 
09/01/82 13107 
09/01/82 
11108 


01TS 
Y 
I I 
I O l r RY 
N o n l 
08/25/82 03:33 
08125182 03:33 


DITB 
ZZ 
11 
l 0 1 1 RY 
NOnl 
08/25/82 03:36 
0 8 / 2 5 / 8 2 03;38 


SETDEF 
CUM 
41; 
28 01, RD 
None 
08/25/82 09:38 


SUBMIT 
I X 2 
1 I 
I Dxr RO 
None 


s w n n 
1 x 1 
51 
13 01, 
RO 
on. 


T o t a l B ~ t l r 
= 
I 4 I T o t a l R l c o l d l = 
77 
Fl1.r 
Found . 
7 


0 
% 
1 
1 
0 
% 
= 
10 
U%.d/llax 
D l l E n l l l e l 1 0 1 D I l V l C: 
111 81 


The following is sample output of the [SIZE] option display format 
shown ~n the second example of the DIR command: 


Dlr.ctorr 
f o r Drlu. 
C i 
User 
0 


C: DITS 
D l K 
ll : 0115 
1E5 
11 : 0115 
Y 
II 


C: 0115 
22 
1% z SETIIEF 
COM 
4 I 2 SUBMIT 
IXZ 
I t 


Cr SUOIIIT 
T X 1 
51 1 


T o t a l Brl.l 
. 
10K 
T0I.I 
R I C o I d . . 
77 
FI1.I 
Found : 
7 


I 
I 1 
= 
L1 
U s ~ d l l l a x D l r E n t r i e s for D r i v l C i 
11, 
64 


Both the hll format and the size format follow their display with two 
lines of totals. The first line displays the total number of kdobyrrs, the 
total number of records, and the total number of files for that drive 
and user area. The second line displays the total number of 1K blocks 
needed to store the listed file. The number of 1K blocks shows the 
amount of storage needed to store the files on a single density disk, or 
on any drive that has a block size of one kdobyrr. The second line also 
shows the number of directory entries used per number of directory 
entries available on the drive. 


A > D I R t D R I V E = C , F F I 


DIR sends a form-feed to the printer before displaying the files on 
drive C. 


The preceding example displays all the files on drive D with Read- 
Write and SYS am~butes. 


A > D I R C : CUSER=hLLI 


Displays all the filcs under each user number (0-15) on drive C 


R>DIR CUSER=ZI 


Displays all the filcs under user 2 on the default drive. 
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This example displays all the filcs under uscr numbcn 3, 4, and 10 on 
drive C. 


& > D I R t D R I V E = A L L l 


Displays all the filcs under uscr 0 on all the drives in the drive search 
chain. (See the SETDEF command.) 


4 & > D I R C D R I V E = C I 


Displays all the files under user 4 on drive C. 


Displays all the files under user 0 on drrvcs B and D. 


A > D I R C e w c l u d e l r.COM 


The preceding example above lire all the files on the default drive and 
user 0 that do not have a filetype of COM. 


A > D I R C u r e r = a l l , d r i ~ e = a l l ~ s ~ s I * . P L I * ~ C D M * . A s M 


The preceding command line instructs DIR to list all the system files of 
type PLI, COM, and ASM on the system in the currently active drives 
for all the uscr numbers on the driver. 


The precedxng command searches all drives under each user number for 
X.SUB. During the search, DIR displays the dnves and user numbers. 


The preceding example tnatructs DIR to display the filename 
TESTRLE.BOB if it is found on any logged-in drive for any user number. 
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The preceding example instructs DIR m list each Read-Write file that 
resides on drive D with its sire in hlobytes. Note that D: is equivalent 
m D:'.'. 
- 
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The DUMP Command 


'Ihc DUMP Gmmsnd 


Sylltnx: 
DUMP filespec 


Explanetion: Dump displays the contents of a file m hcxadectmal and ASCII format. 


Exmplc: 
A >DUMP 46C. TEX 


Console output can look like the following: 


DUMP - V l r r l o n 3.0 
0000, a, 42 a3 OD OII 1a I S 45 OD 04 47 4s 49 OD on la ~DC.,DEF..CHI..~. 
0010: 10 La LA LL LII LII 14 LA LLI ! I III ! I 11 11 18 I4 ..l....l..l....., 
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The ED Command 
- 


Sptax: 
ED {input-filespec (d: I output-filespec}} 
- 


Explanation: The ED transient utility lets you mate and edit a disk file. 


The W utility is a line-onentcd contur editor. This means that you 
create and change character files line-by-lme, or by referencing individual - 


characters with!" a line. 


The ED utility leu you create or alter the file named in the file spcifi- - 
cation. Refer to Section 6 for a description of the ED utility. 


The ED utility uses a portion of your user memory as the active text - 
buffer where you add, delete, or alter the charactem in the file. You use 
the A command to read all or a ort ti on of the file into the buffer. You 
use the W or E command to write all or a portion of the characters from 
the buffer back to the file. 
- 


An imaginary character pointer, called CP, is at the beginnrng of the 
buffer, between two characters in the buffer, or at the end of the buffer. - 


You interact with the ED utilxty m ather command or inwn mode. ED 
displays the ' 
prompt on the s-n 
when ED is in command mode. When 
the ' appears, you can enter the single lmer command that mads text - 


from the buffer, moves the CP, or changes the ED mode of operation. 
When in command mode, you can use the line-editmg characten CTRL- 
C, CTRL-E, CTRI-H, CTRL-U, CTRI-X, and RUBOUT to edit your - 
input. In insert mode, however, you use only CTRL-H, CTRL-U, CTRL- 
X, and RUBOUT. 
- 


- 
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- 
Table 5-6. ED Command Summary 


Command 
Action 


- 


"A 


Append n lines from original file to memory 
buffer. 
- 


OR 


- 
Append file until buffer a one half full. 


"A 
- 
Append file until buffer is full (or end of file). 


- 


/D' -B 


Move CP m beginning (B) or bottom (-B) of 
buffer. 


Move CP n characters forward (C) or back (-C) 
rhrough buffer. 


Delete n characters before (-D) or from (D) thc 


Save new file and rerum to CP/M 3. 


Find character string. 
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Table 5-6. (continued) 


Command 
Act~on 


Save the new file, then reeda, using the new file 
as the original file. 


Enter Insert mode; use T Z or ESCape to exit 
insert mode. 


I 
Insert string at CP. 
I 


Note: upper-case I forces all input to upper-case; while lower-case 
i allows upper- and lower-case. 


Juxtapose strings. 


" K . -nK 


Delete (kill) n lines horn the CP. 


nL 6 - n L , OL 


Move CP n lines. 


nncornmands 


I 
Execute commands n times. 
I 


In'-" 
Move CP n liner and display that Ime. 
1 


DIGITAL RESEARCH" 
5-32 
- 


- CP/M 3 User's Guide 
Thr ED Command 


Table 5-6. (continued) 


Commnd 
Acnon 


In: 
Move to linen. 
- 
:ncormand 


Execute command through line n. 
I 


Enended find string. 
- 
- 
Rerum to orignal file. 


Move CP n lrner fornard and display n lines at 
console. 
- 


1 
Abandon new file, return to CP/M 3. 
I 


Read X$$$$$$$.LIB file into buffer. 


R f i l e s ~ e c < : Z > 


- 
I 
Read filespec into buffer. 
I 


- 


S d e l e t e s t r i n g * Z l n s e r t strinsl:Z> 


Substitute string. 
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Table 5-6. (continued) 
7 


Command 
Action 


"T t - n T , OT 
I 
Type n lines. 
I - 


Line numbering onloff, dlrplay free buffer space. - 


- 


nX<:Z> 


Write n lines to filespec or append ~f previous x 
command applied to the same file. 
1 - 


Write or append n hnes to X$$$$$$$.LIB. 


nXliles~ee<:Z> 


ox<:z> 


Delete filespec. 


- 


" Z 


Wait n seconds. 
- 
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Section 6 gives a detailed description of the overall operation of the ED 
utility and the use of each command. 


If you do not include a mmmand tail in the ED command, ir prompts 
you for the input filespec and the output filespec as follows: 


E n t e r I n p u t F i l e : 


Aker you enter the input filespec, ED prompts agam: 


E n t e r O u t r u t F l l e : 


Enter a filename or drwe ~f you want the output file or in locatton to 
be different from that of the input file. Press RETURN if you want the 
output file m replace the input file. In this case, rhe input file is renamed 
to type BAK. 


If the second file specification contains only the drive specifier, the 
second filename and filetype become the same as the first filename and 
filetype. 


If the file given by the first file specification is not present, ED creates 
the file and writes the message: 


NEW F I L E 


If the file given by the first filespec is already present, you must issue 
the A command to read portions of the file to the buffer. If the size of 
the file docs not exceed the sire of the buffer, the command 


reads the entm file to the buffer 


Ihe i (Insert) command placer ED in insert mode. In this mode, any 
characters you type are stored in sequence in the buffer rtarttng at the 
current CP. 


Any singlc letter commands typed in insert mode are not interpreted as - 
commands, but are rimply stored in the buffer. To return from Insert 
mode to command mode, press CTRL-Z or the ESC key. Note that 
you can always subrt~Nte the ESC key for CTRL-Z In ED. 
- 


The single letter commands arc usually typed ~n lower-case. The com- 
mands that must be followed by a character sequcna end with CTRL- 
Z if they are to be followed by another command letter. 
- 


Any single letter command typed in upper-case tells ED to internally 
translate to upper-case all characters up to the CTRL-Z that ends the 
command. 


When enabled, line numbers that appear on the left of the screen take 
the form: 


where nnnnn is a number in the range 1 thmugh 65535. Line numbers 
are displayed for your reference and arc not contained in either the 
buffer or the character file. The screen line starts wlth 


when the CP a at the beginning or end of the buffer 


If not already pramr, this command line meats the file MWROG.PAS 
on drive A. The command prompt 


:* 


appears on the scmn. This tells you that the CP is at the begnning of 
the buffer. If the file is already present, issue the command 


to fill the buffer. Then type the command 
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to fill the screen wah the first n lines of the buffer, where n 1s the 
current default page rise (See the DEVICE mmmand to set the page 
size). 


Type the command 


to nop the ED utility when you are finished changing the character file. 
The ED utility leaves the original file unchanged as MYPROG.BAK 
and the altered file as MYPROG.PAS. 


The orlelnal file is MYPROG.PAS on the default drwe A. We orleinal 
file remains unchanged when the ED utility finlshes, with the altered 
file stored as NEWPROG.PAS on drwc 8. 


The ED.COM file must bc on drive B. The original filers MWROG.PAS 
located on drive A. It remains unchanged, with the altered program 
stored on drwe B as MYPROG.PAS. 
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The ERASE Command 
- 


Syntax 
ERASE {filesped ([CONFIRM]) 


Explanation: T h e ERASE command removes one or more files from a disvs direc- 
tory in the current user number. Wildcard characters are accepted in 
the filespec. Directory and data space are automatically redaimed for 
later use by another file. The ERASE command can be abbreviated to 
ERA. 


Use the ERASE command with care because all files m the current user 
number that satisfy the file specification are removed from the disk 
directory. 


Command lines that take the form 


ERASE {d:)wddcard-filespec 


require y o u confirmatton because they erase an entire group of files, 
not just one file. The system prompts with the following message: 


Respond with y if you want to remove all matching files, and n d you 
want to avoid erasing any filer. 


If no files match the file rpedficarion, you see the following message: 


The CONFIRM option informs the system to prompt for verification 
before erasing each file that matches the filespec. You can abbreviate 
CONFIRM to C. 


If you use the CONFIRM optlon with wildcard-filespec, then ERASE 
prompts for confirmatmn for each file. You can selectively erase the 
files you want by responding Y to the confirm message, or keep the 
files by responding N to the confirm message. 


- CP/M 3 UK?S Gidc 
T h e ERASE Cmmnnd 


Examples: 
&>ERASE X , PAS 
- 


lhgs command removes the file X.PAS from the d~sk in drive A 


fie system asks to confirm: 


All files with the filetype PRN are removed from the dlak in drlvc A. 
- 


B > E R A A : b Y r . r L C O N F I R b I 


Each file on drive A with a filename that begins with MY is displayed 
with a question mark for confirmation. Type Y to erase the file dis- 
played, N to keep the file. 


- 
All files on drive B arc removed fmm the dxsk. 
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The GENCOM Command 
- 


Syntax: 
GENCOM {COM-filespec) {RSX -filespec)... 


{[LOADER(NULLlSCB 
= (offset,valuc)l) 
- 


Explanation: The GENCOM command is a transient utility that creates a special 


COM file with attached RSX filer. RSX files am used as Resident Sys- 
tem Extensions and are discussed in detail in the CP/M Plus (CP/M - 


Verrton 3) Operating System P~ogrammer's Guide. GENCOM places a 
special header at the beginning of the output program file to indlcatc 
to the system that RSX loading is required. It can also set a flag to - 
keep the program loader actlvc. 


Thc GENCOhl command can alro restore a file already proccrrcd by - 
GENCOhI to the orlgnal COhl file w~rhout the hcader and R5Xs 
GFYCOhl has t h e options that hclp you a n a ~ h R5X filer 


The LOADER option rets a flag to keep the program loader active. ' 


(For complete details on the LOADER option read about CP/M 
function 59 in the CP/M P h (CP/M Version 3) Operating System 
Ptagrommcr's Gurde.) This option s uxd only if no RSX files are - 
attached to the COM file. 


1 The NULL option indicates that only RSX files are specified. 
GENCOM creates a dummy COM file for the RSX files. The output - 
COM filename xr taken kom the filename of the first RSX-filespec. 
The SCB=(offset,value) option rets the System Control Block from 
the program by using the hex values specified by (offset,value). For - 
complete derails on the SCB optlon read about CP/M function 49 in 
the CP/M Plus (CP/M Verrzon 3) Operanng System ProgrommerZ 
Guide. 
- 


Attach RSX Files to a COM File 
- 


Syntax: 
GENCOM COM-filespec RSX -filespec... 


{[LOADERISCB = (offsct,value)]) - 
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- Explanation: The precedmg form of the GENCOM command mates a COM file 


w~th a header and attached RSXs. A maximum of 15 RSXs can be 
attached. GENCOM expects the first filespec to be a COM file and the 
following filespecs to be RSX files. Note that the original COM file IS 
- 
replaced by the newly-created COM file. 


Exmple: 
R>CENCOPI PIYPROC P R O PROCZ 
- 
The preceding command generates a new COM file MYPROG.COM 
w~th anached RSXs PROGl and PROGZ. 
- 


Generate a COM File Using only RSX Files 
- Syntax 
GENCOM RSX-filespec {RSX -filcspcc)... 


[NULL {SCB= (ofhet,value))l 


- Explanation: The preceding form of the GENCOM command attaches the RSX files 
to a dummy COM file. GENCOM creates a COM file with the file- 
name of the first RSX-files~ec in the command tail. This format allows 
the system to load RSXs directly 


Example: 
R>CENCOPI PROCI PROCZ CNULLI 


The preceding command creates a COM file PROG1.COM with Rcsi- 
dent System Extensions PROG1.RSX and PROGZ.RSX. 


Restore a File with Attached RSXs to Original COM File 


Syntax: 
GENCOM filename 


Explanation: The preceding form of the GENCOM file takes a file that has already 


been processed by GENCOM and restores it to its original COM file 
format. Thrs form of the command assumes a filetype of COM. 


Example: 
A>GENCOM PIYPROG 


In the preceding command, GENCOM takes MYPROG.COM, strips 
off the header and deletes all anached RSXs to restore It to its original 
COM format. 
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Update (Add or Replace) RSX Files 
- 


Synrax: 
GENCOM COM-filespec RSX -filespec... 


([LOADER ) SCB = (offset,value)J) - 


Explananon: The prcccdln~ form of rhc GENCOM command adds andor replaces 


KSX file to a filc already 
by GENCOM. 


GENCOM mspmr rhe lcst of RSX files. If they arc new, rhry arc addrd - 


ru the file already prucrsxd by CESCOM. If they alrrrdy cxnrr, then 
GENCOM rcplaccr rhr extsnng RSXI wlth rhr new RSX lilcs. 


In the preceding example, GENCOM looks at MYPROG.COM, which - 
is already processed by GENCOM, to see ~f PROG1.RSX and 
PROGZ.RSX arc already attached RSX files in the module. If either 
one is already attached, GENCOM replaces it with the new RSX mod- 
ule. Othcnv~se, GENCOM appends the specified RSX files to the COM - 


file. 


- 


Attach a Header Record 


Syntax: 
GENCOM filename [SCB = (ofkn,valuc), ... I LOADER] 
- 


Explanation: The preceding syntax line attaches a GENCOM header record, with 


the SCB or loader flag set, to a file of type COM that contams no 
RSXs. This form of the command does not attach RSXr to a file. 
- 
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- 


Examples: 
II>GENCDP( FILETWO l l o a d e r l 


The preceding command anaches a 256-byte header record to the file 
FILETWO.COM and mr the loader flag in the header record. 


- 
The preceding mmmand cause the program loader to set byte 1 of the 
System Control Blok to 1 when rt loads FILEFOUR.COM. 


For more infomatton, see functions 49, SetlGcr System Control Black, 
and 59, Load Overlay or Resident System Extensions, in the CP/M Plus 
(CP/M Verston 3) Opnating System Programmer's Guide. 


- a DIGITAL RESEARCHm 


5-43 
- 


Thr GET Command 
CP/M 3 User's Guide 


The GET Command 


Spou: 
GET {CONSOLE INPUT FROM) FlLE filespec 


{[{ECHO(NO ECHO}ISYSTEM]) 


GET (CONSOLE INPUT FROM) CONSOLE 


Explanation: The GET command is a transient utility that directs CP/M 3 to take 
console input from a file. The file can contain CP/M 3 system com- 
mands andior input for a user mowam. If you use the SYSTEM option, 
GET immediate& takes the n&t system command from the file. 


Console input is taken from a file until the program terminates. If the 
file is exhausted before program input is terminated, the program look. 
for subsequent input from the mnsdc. If the program terminates btfore 
exhaustmg all its input, the syrtcm reverts back m the console for 
con90le input. 


When the SYSTEM option is used, the syrtcm immediately goes to the 
file specified for console input. If you omit the SYSTEM option, you 
can enter one system command m initiate a user program whose con- 
sole input s taken from the file speclficd in the GET command. The 
system reverts to the console for input when it reacher the end of the 
GET file input. The system also rcvcm to the console for console input 
if a GET CONSOLE INPUT FROM CONSOLE command is included 
in the rnput file. 


Get Console Input from a File 


Syntnx: 
GET {CONSOLE INPUT FROM} FlLE filespec {[optionsll 


Explmadan: The preceding form of the GET command tells the system to get sub- 
sequent console input from a file. Table 5-7 listo the GET options that 
you use in the followrng format 


[(ECHO I NO ECHO) I SYSTEM] 
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Table 5-7. GET Onions 


Option 
I 
Meming 


ECHO 
specxfies that the mput is echoed to the console. 
This is the default option. 


NO ECHO 
specifier that the file input is not to be echoed to 
the console. The program output and the system 
prompts are not affected by this option and are 
still echoed to the console. 


SYSTEM 
specifies that all system input is to be takcn from 
the disk file specified in the mmmand line. GET 
takes sysvm and p q a m lnput from the file until 
the file is exhausted or until GET reads a GET 
console command from the file. 


Examples: 
I > C E T F I L E XINPUT 
I>flYPROG 


The preceding sequence of commands tells the system to a h a t e the 
GET utility. However, because SYSTEM is not specified, the system 
reads the next input line from the console and executes MYPROG. If 
MYPROG program requircs console input, it is takcn from the filc 
XINPUT. When MWROG terminates, the system reverts to the con- 
sole for console input. 


A > C E T F I L E X I N Z CSYSTECI 


The preceding command immediately d i e m the system to get subse- 
quent console input from filc XlN2 because it includes the SYSTEM 
option. The system reverts to the console for console input when it 
reaches the end of file in XIN2. Or, XlN2 can redirect the system back 
to the console !fir contains a GET CONSOLE command. 
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Terminate Console Input from a File 


Syntur. 
GET {CONSOLE INPWT FROM) CONSOLE 


Explanation: The preceding form of the GET command tells the system to get mn- 


sole input from the console. 


Example: 
R>CET CONSOLE 


The preceding GET command tells the System to get console input from 
the mnsole. You can use this command in a file (previously specified in 
a GET FILE mmmand) which IS already being read by the system for 
console input. It is used to redirect the console input to the mnsole 
before the end of the file is reached. 
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The LIST option is the same as NOPAGE, except that it eliminates 
extra lines between heading. Use this option with CTRL-P to list 
the hdp information on the printer. 


The ~rcccding command displays a list of topics for which hdp is 
available. 


A>HELP DATE 


This command displays general informat~on about the DATE wm- 
mand. It also displays any available subtopics. 


A>HELP D I R OPTIONS I N 1 


The preceding command indudes the subtopic options. In response, 
HELP displays information about options associated wlth the DIR 
command. The display is not in paged mode. 


A>HELP ED 


The preceding command displays general information about the ED 
utility. 


A >HELP ED COMMANDS 


This form of HELP displays information about commands internal to 
ED. The preceding example can also be entered as 


Add Your Own Descriptions to the HELP.HLP File 


Syntax: 
HELP [EXTRACT] 
HELP [CREATE] 
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on: CP/M 3 is dismbutcd with ovo rcland HELP files: HELP.COM and 


HELP.HLP. The HELP.COM file is the command file that processes 
the ten of the HELP.HLP file and displays it on the screen. The 
HELP.HLP file IS a text file to which you can add customircd mforma- 
tion, but you cannot directly cdrt the HELP.HLP file. You muat use the 
HELP.COM file to convert HELP.HLP to a file named HELP.DAT 
before you can edit or add your own ten. 


This form of the HELP command has the following options: 


The EXTRACT option accesses the file HELP.HLP on the default 
drive and creates a file called HELP.DAT on the default drive. You 
can now invoke a word processing program to edit or add your own 
nn to the HELP.DAT file. EXTRACT can be abbmviated to E. 
The CREAn opuon accesses your edited HELP.DAT file on the 
default drive and builds a mised HELP.HLP file on the default drive. 
CREATE can be abbreviated to C. 


You must add topics and subtopics to the HELP.DAT file m a spcdfic 
format. A topic heading in the HELPBAT file takes the form: 


Thc three badislashes am thc topic delimit= and must begin in col- 
umn one. In the preceding format statement, n is a number in the range 
from 1 through 9 that signifies the level of the topic. A main topic 
always has a level number of 1. The first subtopic has a level number 
of 2. The next lwel of subtopic has a level number of 3, and so forth, 
up to a maximum of nine lwels. Topicname is the name of your toprc, 
and allows a maximum of twelve charact=. The entire line is tcrmi- 
natcd with a carriage r a m . 


Use the following guidelines to edit and insert text into the HELP.DAT 
file. 


m Topics should be placed in alphabetical order. 


1 Subtop~cs should be placed alphabetically wrthin then respective 


supertopic. 


1 Levels must be indicated bv a number 1-9. 
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Some examples of topic and subtopic lines in the HELP.HLP file follow 


IIIINEW UnLITY<cr> 


III2COMMANDS<cr> 


The first example illustrates the format of a main topic line. The second 
example shows how to number the first subtopic of that main topic. 
The rhlrd example shows how the " e n level subtop~ under level 2 
should be numbered. The fourth example show how to return to the 
lower level rubrop~c. Any topic name with a level number of 1 is a 
main topic. Any topic name with a lcvcl number of 2 is a submpic 
within m main toplc. 


When you are executing the HELP.COM file, you need only mter enough 
letters of the topic to unambiguously identify the mptc name. When 
referencing a subtop~c, you must type the topic name AND the sub- 
topic, othenvtse the HELP program cannot determine whtch main topic 
you arc referencing. You can also enter a topic and subtopic following 
the program's internal prompt, HELP>, as follows 


This form of HEW displays information about commands internal to 
the editing program, ED. 
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The HEXCOM Command 


Syntax 
HEXCOM filcnamc 


Emlanation: The HEXCOM command is a transient utilitv that eencratcs a com- 
. 
.. 


mrnd file ifilctypr C0.M) from a HEX mput file. It names rhr oucpur 
file wlrh rhc same filcnamc as the lnput 61c but wnrh filnypc COII. 
HEXCOM always lookr for a file w ~ r h filcrypc HEX. 


Example: 
& >HEXCOM B r PROGRAM 


In the preceding command, HEXCOM generates a command file 
PROGRAM.COM from the input hex file PROGRAM.HEX. 


The INITDIR Command 


Syntax 
INITDIR d: 


Explanation: We MITDlR command can initialize a disk director/ to allow date 
and time stamping of fils on that dlsk or remove date and time stamps. 


You must use INlTDlR to inttialize the directory far any disk on which 
you plan to record datc and time stamps for your files. If the d~sk a 
blank WITDIR iturializa the directon, to record date and time stamor. 
Ir filr; alrcady exnit on the dlrk, I N ~ ~ D I R 
check\ rhc ,pa,r avallablc 


for dare and rlmc ,ramps ~n the d~rccror~. 
If rhcrc Is nor enough n,om 


for date and tame stamps, INlTDlK doer not ~nlrtalrzc the d~rccrory and 
returns an error message. 


Aker you mltialize the d i m r y for date and time stamps, you must 
ux the SET command to spcclfy time stamp options on the disk. 


Examples: 
R > I N I T D I R C : 


The system prompts to confirm: 


INlTDtRWILL I C T I V R T E T I M E S T R M P S F D R S P E C I F I E D D R l V E + 
Do y o u r e a l l r want t o r e - f o r m a t t h e d i r e c t o r y : C I Y I N I ~ 


If the directory has previously been initiahred for date and time stamps, 
INITDIR displays the message: 


D i r e c t o r y a l r e a d y r e - f o r m a t t e d 
Do 
Y O U u i s h t o I ~ E O V ~ P 
d a t e l t ~ m e d i r e c t o r v s p a e e 


I Y I N ) ' 


Enter Y to relnltlalirc the directory to eliminate date and time stamps. 
If you enter N, date and time stamping remains anwc on your dlsk 
and INITDIR displays the following message: 


Do r o u u a n t t h e r u i s t i n I d a t e l t ~ m r st as^^ c 1 1 a r d IYINI' 


Enter Y to clear the cxistlng stamps. Enter N to keep the exsting datc 
and rime stamps. 


ODlClTAL RESEARCH'" 
5-52 


CP/M 3 User's Guide 


The LIB Command 


The LIB Cmm.nd 


Syntax: 
UB filespec(IllMIPID1) 
LIB filerped[llMlP]}= file~pec{modifier} 


{,filespec(modifier} ... 1 


Explanation: A library file contains a collection of abject modules. Use the LIB utility 
to create hbrarier, and to append, replace, select, or delete modules 
from an exlstlng hbrary. You can also use LIB to obtain information 
about the contents of library files. 


LIB creates and maintains hbrary files that contam object modules in 
Microsoft" REL format. These modules are produced by Digital 
Research's relocatable macro-assembler program, RMAC, or any other 
language translator that produces modules in MiuoSok REL format. 


LINK-80" links the object modules contained in a library to other 
object filer. LINK-80 automatically selects from the ltbrary only those 
modules needed by the program bcmg Imked, and then forms an exc- 
cutable file with a filetype of COM. 


The library file has the filetype REL or IRL depending on the option 
you chwre. Modules m a REL library file must not contain backward 
references to modules that occur earlier in the hbrary, because LINK- 
80 currently makes only one pass through a library. 
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/ 
M 
The MODULE option displays module names. 
I 


Table 5-8. LIB Options 


I 


The PWLlCS uprlon dgrplayr module name5 and thc 
puoltc varmblcr for rhc ncw llbrnry file. 


Optron 


I 
The DUMP option displays the contents of object 
modules ~n ASCII form. 


Meaning 


Use modifiers in the command line to insrmct LIB to delete, replace, or 
select modules in a library file. Angle bracken enclose the modules to 
be deleted or replaced. Parentheses cndose the modules to be selected. 


I 
The INDEX option creates an indexed library file of 
rype IRL. LMK-80 searches faster on indexed Ilbrar- 
ler than on nonindexed libraries. 


Unless otherwise spec~fied, LIB assumes a filetype of REL for all source 
filenames. When you follow a filename by a group of module names 
endosed in parentheses, these modules are included in the new library 
file. If modules are not specified, LIB indudes all modules from the 
source file in the new library file. 


1 Delete 
<module = > 
I 


Tablc 5-9. LlB Modihcn 


1 Replace 
<module = filename,REL> 
I 


Modifier 


If module name and filename arc the same this 
shorthand can be used: 


<filename> 
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The Pnt examplc d~rplayr all moduln and publlcr ~n TEST4.REL. The 
second cxamplc creates TESTS.REL kom FILtI.REL and FII.EZ.REL. 
and dtrplnyr 311 modulrr and publtcr ~n TFSTS.RFI.. 


In the preceding example LIB creates a library file TEST.REL from 
modules in rwo sour- files. TESTI.REL mntribum MOD1 and MOD4 
LIB extra- 
modules C1, C4, all the modules located h e e n them, 


and module C6 from TEST2.REL. 


In this example, LIB mates EILEZ.REL from FILE3.REL, omining 
MODA which is a module in FILE3.REL. 


In the fint example, MODA is in the existing EILrn.REL. When LIB 
creates FILE6.REL from FILES.REL, FILEB.REL replaces MODA. 


In the ~ m n d 
example, module THISNAME a in HLES.REL. When 


UB mates FILE6.REL. from FILE5.REL the file THISNAME.REL 
replaces the similarly named module THISNAME. 


A > L I B F I L E I I I J = ~ : F I L E ~ ~ P L O T S , F I N D I ) S E A R C H - D I S P L A Y ~ 


In this example LIB creates FILE1.IRL on drive A kom the selected 
modules PLOTS, FIND, and modules SEARCH through the modulc 
DISPLAY, in FILE2.REL on drive B. 
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The LINK Command 
- 


Syntax 
LlNK d:{filespec,{[ol}=)filespec([o]H, ... 1 


Explalanatioo: The LINK mmmand mmblnes relocatable oblea modules such as those 


produced by RMAC and PUI-80" into a .COM file ready for execu- 
tion. Relocatablefilescanconta~nextemal 
referencesandpubl~cs. Relocat- 


able files can reference modules in ltbrary files. LINK searches the llbrary 
files and lncluder the referenced modules in the output file. The LlNK 
command is the LINK-80 utiliry and are synonymous in this discussion. 
See the Programmer's Utilities Gutde for the CP/M Family of Operot- 
mg Systems for a complete description of LINK-80. 


You can use LlNK option switches to control the uecutlon paamctcrs 
of LINK-80. LINK options follow the file specifications and are rndorcd 
within square brackets. Multiple switches are separated by commas. 


Optton 


Dhhhh 


Lhhhh 


Mhhhh 


NL 


Table 5-10, LINK Options 


temporary data to disk. 


BlOS link ~n banked CP/M 3 system. Ahgns data 
segment on page boundary; puts length of code seg- 
ment in header; defaults to SPR filetype. 


Data origin; sen memory origin for common and 
data area. 


Go; set start address to label n. 
I 


Load; change default load address of module m hhhh. 
Default 0100H. 


Memov size; define free memory requirements for 
MPIM" modules. 


No listing of symbol table at console. 
I 
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Output COM command file. Default. 
I 


Table 5-10, (continued) 


lop 


Output PRL page relocatable file for execution under 
MPIM in relocatable segment. 


Option 


Output RSP Resident System Process file for execu- 
tion under MPIM. 


Meaninz 


Ios 


Output SPR System Page Relocatable file for uecu- 
tion under MPIM. 


NR 
No symbol table file. 
1 


Phhhh 
Program orign; changer default program origin 
address to hhhh. Default 1s 0100H. 


Q 
Lists symbols with leadng question mark. 


S 
Search precedtng file as a library. 


SCd 


$Id 


SLd 


Sod 


SSd 


Destination of console messages, d, can be X for 
console, Y for printer, or Z for zero output. Default 
is X. 


Source of intermediate fila; d is disk drive A-P. 
Default is current dnvc. 


Source of library files; d is dlsk drxve A-P. Default is 
current drive. 


Dcstinatlon of object filc; d can be Z, or disk drwe 
A-P. Default is to same drwe as first file rn the LINK- 
SO mmmand. 


Destination of symbol file; d can be Y , 2, or disk 
drive A-P. Default is to same drive as first file in 
LINK-80 command. 


Examples: 
A>LINK b:PIYFILETNRJ 


LINK-80 on drive A use as input MYFILE.REL on drive B and pro- 
duas the executable machlnc code file MYFILE.COM on drive B. The 
[NR] option spec!fics no symbol table file. 


LINK-80 mmbinca the separately compiled Mes ml, m2, and m3, ~ I V C I 
their external references, and produces the executable machine code file 
rn1.COM. 


UNK-80 combines the separately compiled files ml, mZ, and m3 and 
produces the executable machine code file m.COM. 


The [s] option tells LINK-80 to search FILES as a library. LINK-80 
mmbmcs MYFILE.REL with the referenced subroutines contained ~n 
FILES.REL on the default drive A and produces MYFILE.COM on 
drwe A. 
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The MAC Command 


Syntur: 
MAC filename {$options) 


Explanation: MAC, the CP/M M a w Assembler, is a uanricnt utility that reads 
assembly language statements horn a disk file of filetype ASM. MAC 
assembles the statements and produces three output files with the input 
filename and output filetypes of HEX, PRN, and SYM. 


Filcname.HEX contains Inrel' hexadecimal format object code. You 
can debug the HEX file with a debugger, or use HEX COM to create a 
COM file and execute it. 


Filename.PRN contains an annotated source listing that can be printed 
or wamined at the console. The PRN file includes a 16-column wide 
lirtine at the left side of the oaee that shows the values of literals. 
. - 


machine code addresses, and generated machine code. An equal sign 
denotes literal addresses m ehminate confusion w~th machine code 
addresser. 


Filename.SYM contains a sorted lisr of symbols defined in the program. 


Before invoking MAC, you must prepare a source program file with 
the filetype ASM containing assembly language statements. 


You can dirm the input and output of MAC using the options listed 
in the following table. Use a letter with the option to indicate the 
source and destination drives, console, printer, or zero output. Valid 
drwe names arc A through 0. 
X direm output to the console. P directs 


output to the printer. Z specifies that output files will not be created. 


O DIGITAL RESEARCH" 
5-59 


Table 5-11, Input/Output Options 


Option 
Meaning 


source drive for ASM file (A-0) 


destination drive for HEX file (A-0, Z) 


source drive for ma- 
library LIB files called by the - 


1 
MACLIB m m e n t . 


I 
destination drive for PRN file (A-0, X, P, 2) 
I - 


S 
destination drive for SYM file (A-0, X, P, Z) 


Table 5-12, Output File Modifiers 


I Modifier I 
Meaninn 
- 


lirts input lines mad from macro library LIB files 
suppres~s listing (default) 
! - 


lirts all macro lines as they arc processed during 
assembly 
suppresses all macro lina as they arc read during 
assembly 
lists only hex generated by macro expansions 


- 


lists all LOCAL symbols in the symbol list 
suppresses all LOCAL symbols in the symbol list 
(default) 


appends symbol file to print file 
suppresses creation of symbol file 


- 
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- 
- 


+ 1 
produces a pass 1 listing for macro debugging in 
PRN file 
-1 
suppresses listing on pass 1 (default) 


- 
- 


Examples: 
A>MAC SAMPLE 


In the preceding example MAC is invoked from drive A and operates 
on the file SAMPLEASM also on drive A. 


In thts example, an assembly option parameter list follows the MAC 
command and the source filename. The parameten dirm the PRN file 
to drive B, obtain the ASM file from drwc A, direct the HEX file to 
drive B, and send rhe SYM file to the console. You can use blanks 
between option parameten. 
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The PATCH Command 
- 


Syntax: 
PATCH filename {ryp} {n) 


Explanation: The PATCH command displays or installs patch number n to the 


CP/M 3 system or CP/M 3 command files. 


Only CP/M 3 system fils of film COM, PRL, or SPR can be patched 
wth rhc PATCH command. If the ryp option is not specified, the PATCH 
utility looks for a file with a filetype of COM. 


The patch number n must be between 1 and 32 inclusive 


Examples: 
A > PATCH SHOW 2 


The preceding command patches the system SHOW.COM file with 
patch number 2. The system displays the following question: 


Do v o u w a n t t o l n d i e a t e t h a t p a t c h a2 
has been i n s t a l l e d f o r S H O W , C O M ? Y 


If the patch is successful, the system displays the message: 


P a t c h I n s t a l l e d 


If the patch is not successful, the system &splays the following mes- 
sage: 


One of the following error messages might be displayed: 


ERROR: Patch requires CP/M 3. 
I ERROR: Invalid filerype clp 
I ERROR: Serial Number mismatch. 


ERROR: Invalid parch number n 
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Synrax: 
PIP dest -filcspccld:{[GnlI=src-filespe4[01HX... I d: {[oll 


Whation: PIP is a nansicnt utility that copies one or more files from one disk 


andfor user number to another. PIP can rename a file after copying it. 
PIP can combine two or more files into one file. PIP can also copy a 
character file from disk to the prtnter or other auxxliary logical output 
device. PIP can create a file an disk fmm rnpur from the console or 
other logical lnput device. PIP can transfer data from a logrcal input 
dev~ee to a logical output device, thus the name Peripheral Interchange 
Program. 


PIP copies file attributes with the file. This indudcs Read-Write or 
Read-Only and SYS or DIR file anributn and the user-definable ami- 
butes El through F4. If a file is password-protected, you must enter the 
password m the command line following the filename and/or filerype to 
which it belongs. If the password fails, the file is skipped and the failure 
noted. 


When you specify a destination file with a password, PIP assigns that 
password to the destlnarion file and automatically sets the password 
protectton mode to READ. When you specify a destination file with no 
password, PIP does not assign a password to the dest~nation file. When 
you spcclfy only a destinatlon drive, PIP assigns the same password and 
password protection mode to the destination file as specified in the 
source file. When you specify a destinatlon file with a password, PIP 
automatically sets the password protection mode to READ. This means 
that you need a password to read the file. (SK the SET command.) 


Single File Copy 


Syntax 
PIP d:{[Gnl) = src-filespe4[options]) 


PIP dest-filcrpe4[Gn]] = d:{[options]) 


PIP dew-filespec([Gn]] = src-filerpec{[o]) 
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Explsnation: The first form shows the simplest way to copy a file. PIP looks for the 
file named by rrc-filespec on the default or optionally specified dtive. 
PIP coptes the file to the drive specified by d: and gives it the name 
specified by src-filespec. If you want, you can use the [Gn] optlon to 
place your destinatnon file (de~t-filespec) in the user number specified by 
n. ?he only option recognized for the destination file is [Gn]. Several 
options can be combtncd together for the source file specification (src- 
filespec). See the Table 5-13, PIP options. 


The second form is a variation of the first. PIP looks for the file named 
by dest-filespec on the drive specified by d:, coplcs a to the default or 
oprionally spKified drive, and giver it the name spKified by dert-filespec. 


T h e rhtrd form shows how to rename the file after you copy it. You 
can copy it to the same drive and user number, or to a different drlve 
and/or user number. Rules for opt~ons are the same. PIP looks for the 
file specified by src-filespec, copies it to the location specified in dert- 
filespec, and gives it the name indicated by dest-filespec. 


Remember that PIP always goes to and gets from the current defaulr 
user number unless you specify otherwise with the [Gn] optton. 


Before you start PIP, be sure that you have enough free space in kilo- 
bytes on your destination disk to hold the ent~re file or files that you 
are copying. Even ~f you are replacing an old copy on the destination 
dlsk wtth a new copy, PIP still needs enough room for the new copy 
before it deletes the old copy. Use the DIR command to determine 
filcslzc and the SHOW command to determine dlsk space. If there is 
not enough space, you can delete the old copy first by using the ERASE 
command. 


Data is first copied to a temporary file to ensure that the entire data file - 
can be constructed ~n the space available on the dtsk. PIP gives the 
temoorarv file the filename s~ec~fied 
for the destinat~on, with the file- 
. . 
type $$$. If the copy operation is successful, PIP changes the temporary - 
filetype $$$ to the filetype specified in the destmatlon. 


If the copy operation succeeds and a file wlth the same name as the 
dertinat~on file already exists, the old file with the same name is erased - 
before renaming the temporary file. 


CPlM 3 UKI'I Guide 
The Pm Gmmand 


File attributes (DIR, SYS, RO, RW) are transferred with the files 


If the existing destination file i s m to Read-Only (RO), PIP asks yuu rf 
you want to delete a. Answer Y or N. Use the [Wl optton to wrlte over 
Read-Only files. 


You can include PIP options following each source name. There is one 
valid option ([Gnl-go to user number n) for the desunation file spec,. 
ficstion. Options are endosed in square bradicts. Several opttons can 
be included for the source files. They can be packed togerhcr or sepa- 
rated bv maces. Onrions can vcrifv that a file was cooled correctlv 
. . 
. 
allow PIP to read a lile xrh thc .;urm 
SYS mrlbut;, 
cause PIP ;d 


wrmrr over Kead.Only lilts, cmrc PIP ru put a file nnro or ropy ~r from 
r ,proficd user number, rran,frr from lowcr- to upprr.cavc, and much 
more. 


Examples: 
R > P I P B : = A : o l d l ~ l ~ + d a t 
A > P I P B : o l d f i l e , d a t = A : 


Both forms of this command cause PIP to read the file oldfile.dat from 
drwe A and put an exact copy of it onto drive B. This is called the 
short form of PIP, because the source or destlnatlon names only a drive 
and does not indude a filename. When usmg this form you cannot copy 
a file from one drwc and user number to the same drive and user 
number. You must put the destination file on a different drwe or in a 
dlffercnt user number. (See the sectton on PIP Optrons, and the USER 
Command.) The second rho* form produces exactly the same result as 
the first one. PIP looks for the file oldfile.dat on dnve A, the drtve 
specified as the source. 


This command copies the file oldfile.dat from drive A to drive B and 
renames a to newfile.dat. The file remains as oldfile.dat on drive A. 
Thcs is the long form of the PIP command, because it names a file on 
both sides of the command line. 
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Using thls long form of PIP, you can copy a file from one drivc and 
user number (usually urer 0 because CP/M 3 automatically stam out 
m user O-the 
default urer number) to the same drive and user number. 


Ths gives you two copies of the same filc on one drive and user num- 
ber, each with a different name. 


The preceding command copies the filc PROGRAM.DAT from user 1 
on drive A to the current selected user number on drive B and renames 
the filetype on drive B to BAK. 


In this command, PIP copies the file named programl.dat on drivc A 
and echoes [El the transfer to the console, verifies [Vl that the two 
copier are exactly the same, and gets [G3] the file programl.dar from 
urer 3 on drive A. Because there is no drivc spec~fied for the dcstina- 
non, PIP automatically copies the file to the default user number and 
drivc, ~n this case user 0 and drive 8. 


Multiple File Copy 


Syntzc 
PIP d:{[Gn]) ={d:)wildcard-filcrpec([~ptions1) 


Explanation: When you use a wildcard in the source specification, PIP copies match- 
ing files one-by-one to the destination drivc, rnaintng the original name 
of each file. PIP drmlavs the messaec COPYING followed bv each 
. , 


filename as the coo" omratton oroceeds. PIP ~ssues an error messaee - 
.,. 
. 
and abonr the copy operation if the destination drive and user number 
are the same as those specified in tbe source. 


This command causes PIP to copy all the files on drive A with the 
filetype COM to drivc B. 
- 
- 


C DIGITAL RESEARCH'" 
5-66 
- 


CP/M 3 Uaa'r Goidc 
The PIP Command 


This command causes PIP to copy all the files on drwe A to drive B. 
You can uw this command to make a backup copy of your disrribu- 
tion dlsk. Note, however, that this command does not copy the CP/M 3 
system from the system tracks. COPYSYS copies the system for you. 


The preceding command copia all fila whose filcnams begin with PROG 
from drlvc A to drive 8. 


A>PIP B:CCII=A:r,BAS 


This command causes PIP to copy all the files wrth a filetype of BAS on 
drive A in the default user number (user 0) to drive B tn user number 1. 
Remember that the DIR,TYPE,ERASE, and othcr commands only access 
files in the same user number from whlch they were invoked. iSee the 
USER Command.) 


Combining Files 


Syntax: 
PIP dest-filespe4[Gn]] = src-filespc4[o]), src-filespec([o]H, ... ] 


Exolmation: This form of the PIP command lets vou soecifv two or more filev in the 
, 
x 
. 
~ 
~~- 
~ 


source. PIP cooies the files soecificd in the source from left to rieht and 


~ 
~- 
- 


combtncr rhcm into one filc wnth the name ~ndocarcd hy rhc derr~narnon 
file ,prc#fiiatwn. Thts proccdurc IS called 61r concarenarnon. You can uu 
the [Gn] option afrer the destination file to place it in the user number 
specified by n. You can specify one or more options for each source file. 


Some of the options force PIP to copy files character-by-character. In 
these cams, PIP looks for a C X - Z character to determine where the 
end of the file is. All of the PIP options force a character transfer wcef 
the following: 
- 
A,C,Gn,K,O,R,V,andW. 


Copying data to or from logical drvices also forces a charaaer tmnakr. 
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You can terminate PIP operations by ryplng CTRL-C. 
- 


When concatenarlng files, PIP only searches the last record of a file for 
the CTRL-Z end-of-file character. However, if PIP is doing a character 
transfer, it stops when it encounters a CTRL-Z character. 
- 


Use rhc 101 opttun 01 you arc concarmatang ma.hnnc coJc liler. The 101 
optlon causo PIP ro ~gnorc embedded (:'1KI -Z md-of-file charancrs. - 
rhjch tndncntc rhc cnd-of-file rharrcrcr mn text tile.. hut mmght hc valid 
data in object code files 


The three files named FILEI, FILEZ, and FILE3 are joined from left to 
right and copied to NEWFILE.$$$. NEWFILE.$$$ is renamed to NEW- - 
FILE upon successful completion of the copy operation. All source and 
desrlnation files are on the dlsk in the default drive A. 


The file Y.BAS on dr~ve A is lolned with Z.BAS from drive B and placed 
m the temporary file X.$$S on drive B. The file XX$S is renamed to 
X.BAS on drive B when PIP runs to ~uccesrful completion. 


Copy Files to and from Auxiliary Devices 


Sptax: 
PIPdnt-filespec{[Gn]) = src-filespec{Iol] 


AUX: 
A m : {lo]) 


CON: 
CON: {bl) 


PRN: 
NUL: 
LST: 
EOF: 


Explanation: This form is a special case of the PIP command llnc h a t lets you mpy 
a file from a disk to a device, from a device to a disk or from one device 
to another. The files must contain printable characters. Each peripheral 
dwicc is assigned to a logical device that ident~fier a source device that 
can transmtt data or a destination dwicc that can receive data. (See the 
DEVICE command.) A colon follows each logical device name so it 
cannot be contused wirh a filename. Enter CTRL-C to abort a copy 
operation that ura a logical devicc m the source or destination. 
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The logical dcvice names are listed as follows: 


1 CON: Console input or output device. When used as a source, usually 


the keyboard; when used as a destinauon, usually the screen. 


I AUX: Aux~liary Input or Output Device. 


1 LST: The destination device assigned to the list output device, usually 
the pnnrer. 


The following three dcvice names have specla1 meaning: 
I NUL: A source dwicc that produces 40 hexadecimal zeros. 


1 EOF: A source device that produces a single CTRL-Z, the CP/M 3 


end-of-file mark. 


1 PRN: The printer device with tab expansion to every eighth column, 
line numbers, and page ejem every sixtieth Imc. 


Examples: 
B > P I P PRN: =CON: rPIYDITA.0A7 


Characters are first read from the mnsale input device, generally the 
keyboard, and sent dirccrly to your pnnter device. You type a CTRL-z 
character to tell PIP that keyboard xnput is complete. At that time, PIP 
continues by rcadinp. character data from the file MYDATA.DAT on 
drwe B. ~ e i u s e PG: 
is the destination device, tabs are expanded, line 
numbers are added, and page qeas occur every sixry lines. 


Note that when the CON: device is the source you must enter both the 
carriage m r n (RETURN) and hne-feed (LF) keys for a new hnc. 


( \ > P I P B:FUNFILE.SUE 
= CON: 


Whatever you type at the mnsole is wrlncn to the file FUNFILE.SUE on 
drive B. End the keyboard input by typing a CTRL-Z. 


R > P I P LST:=CON: 


Whanvcr you type at the console keyboard 1s wrinsn to the list devlcc, 
generally the pnnrer. Terminate input wmh a CTRL-2. 
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The file DRAFT.TXT on drwe B is written to the printer device. Any tab 
characters are expanded to the nearest column that 1s a multiple of 8. 


The preceding command causes PIP to write the file DRAFT.TXT to the 
list device. It automar~cally expands the tabs, adds line numbers, and 
elects pages after skty lines. 


Multiple Command Mode 


Sptax: 
PIP 


Explplanation: This hrm of the PIP command starts the PIP uttlity and lets you type 
multiple command lines while PIP remains in user memory. 


PIP writer an aster~sk on your screen when ready to accept input com- 
mand hner. 


You can type any vahd command line described under previous PIP 
formats following the asrerwk prompt. 


Terminate PIP by pressing only the RETURN key fallowing the asterisk 
prompt. The empty command line tells PIP to discontinue operation and 
return to the CP/M 3 system prompt. 


Examples: 
A > P I P 
CP/M 3 PIP 
VERSION 3.0 


* N E W F I L E = F I L E I , F I L E 2 , F I L E 3 


APROC.COn=BPROC.COM 
A : = B : X + B A S 


r u : = * . * 
*'PI 
a > 


This command loads the PIP progam. The PIP mmmand input prompt, 
*, tells you that PIP e ready to accept commands. The effects of this 
sequence of mmmands arc the same as in the prevrous uamples, where 


- 
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the command line is included in the command tail. PIP is not loaded 
- 
into memory for each command. To exit this PIP command mode, 
press REllJRN or one of its equ~valent control characters, CmL-J or 
CTRL-M as shown. 
- 


Using Options With PIP 
- Explananon: Wtth opnonr you can process your source file ~n vpecnal ways You can 
expand rah chsractcn, rranrlarc from upper to lower-care, cxrran por 
nons of your rcxc, vrrdy that the copy 15 correct, and much more 


Ihc PIP options are listed in Table 5-13 using n to represent a number 
and s to represent a sequence of characters terminated by a CTRL-Z. 
An optlon must immediately follow the file or device it affects. The optlon 
must be enclosed in square bracken [ I . For those options that require a 
numeric value, no blanks can occur between the letter and the value. 


You can indude the [Gn] option after a datinatlon file specification. You 
can indude a lrrr of options after a source file or source device. An option 
hst is a sequence of single letters and numeric values that arc optionally 
separated by blanks and enclosed in square brackets [ I . 
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Table 5-13. PIP M o o s 


Optia 
I 
Function 


A 
Copy only the files that have been modified since the 
last copy. To back up only the filer that have been 
modified since the last back.up, use PIP with the 
I 


archwe option, [A]. 
I 


I 


Pmmpt for confirmation befm paforming each copy 
optration. Use the [C] opuon when you want to copy 
only some files of a particular filetype. 


Dn 
Delete any characten past column n. This parameter 
follows a source file that contains lines t w long to 
be handled by the destination device, for example, 
an SO-character printer or narrow console. The num- 
ber n should be the maximum column width of the 
destination device. 


E 
Echo transkt at console. When this parameter fol- 
lows a source name, PIP displays the source data at 
the console as the copy i s taking place. The source 
must contain character data. 


F 
Filter form-feeds. When t h ~ s parameter follows a 
source name, PIP removes all form-feeds embedded 
in the source data. To change form-feeds set for one 
page length in the source file to another page length 
in the desttnation file, use the F command to delete 
the old form-feeds and a P command to simultane- 
ously add new form-feeds to the destlnatlon file. 


Gn 
Get source from or go to user number n. Wlen this 
parameter follows a source name, PIP searches the 
directory of user number n for the source file. When 
it follows the destinatron name, PIP places the desti- 
nation file in the user number s~cclfied by n. Rlhe 
number must be ~n the range 0 to 15. 
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I 
messages whm errors occur. 


Table 5-13. (continued) 


I 
Ignore :00 records in the transfer of Intel hexadcci- 
ma1 format file. The I option automatically sen the 
H opuon. 


Option 


L 
Translate upper-case alphabetics in the source file to 
lower-case m the destination filc. This parameter fol- 
lows the source device or filename. 


Function 


N 
Add line numbers to the destination file. When this 
parameter follows the source filename, PIP adds a 
hne number to each line copied, starting with 1 and 
lncrementing by one. A colon follows the line mum- 
ber. If N2 is specified, PIP adds leading zeros to the 
line number and Insens a tab after the number. If the 
T parameter is also set, PIP expands the tab. 


H 
Hex dam tnnsfu. PIP checks all dam for proper I n d 
hexadecimal file format. The console disolavs error 


0 
Objcct file transfer for machine code (noncharacter 
and therefore nonpr~ntabkl files. PIP Ignores any 
CTRL-Z end-of-file during mncatenauon and mans- 
fer. Use thls option if you arc combining object code 
files. 


Pn 
Set page length. n specifies the number of lines per 
page. When this parameter modifies a source file, PIP 
xncludes a page qect at the beginning of the destina- 
don filc and at wny n lines. If n = 1 or is not 
spcdfied, PIP insem page ejects mc~y swty lines. When 
you also specify the F optton, PIP ignores form-feeds 
in the source data and Inserts new form-feeds in the 
destinauon data at the pagc length specified by n. 
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Table 5-13. lcontinued) 


Quit mpylng from the source device after the string 
s. When used with the S parameter, this parameter 
can mract a portion of a source filc. The string 
argument must be termmated by CTRL-Z. 


Start copying ham the source device at the string s. - 
The string argument must be temlnated by CTRL- 
Z. When used with the Q parameter, this parameter 
can extract a portion of a source filc. Both stan and 
quit strings are included in the destination filc. i - 


- 


Option 


- 


R 
Read system (SYS) file. Usually, PIP ignores file 
marked wath the system attribute in the disk dlrec- 
tory. But when this parameter follows a source file- 
name, PIP copies system files, including their anri- 
buhs, to the destination. 


'I'n 
Expand rabr. When rhnr parameter follow, a surcc 
filmamc. PIP expands tab CTRL-I) characters ~n rhc - 
dcrtnnraon filc. PIP rcolacrr each (7RL-I wtth moueh 


Funcnon 


- 
- 


spaces to position the next character m a column 
divisible by n. 
- 1 - 


I 


Translate lower-case alphabct~c characters m the 
source file to uppersase m the destmation file. This 
parameter follows the source device or filename. 


- 
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V 
Verify that data has been copied correctly. PIP com- 
pares the destination to the source data to ensure 
that the data has been wri- 
correctly. The dcsti- 


nation must be a disk file. 


- 
- 


- 
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lhlr command constructs rhc file NEWROG.BAS on dnvc A hv loan- 
tng the nvo filer (:OUE.BA\ and DATA.RAS from drwc A. Dur~ng rhc 
copy operanun, CODE.RA5 a mnrlarcd to lowrreu, whdc DA1A.RAS 


Table 5-13, (continued) 


a translated to upper-case. 


& > PIPCON:=WIDEFILE.BASCOBOl 


- 
- 
- 
- 
- 


This command writer the character file WIDEFILE.BAS from drive A 
to the console device, but deletes all characters following the 80th col- 
umn position. 


The file LElTER.TXT from drive A is copied to LElTER.TXT on 
drive 8. The LElTER.TXT file is also written to the screen ar, the copy 
operatlo" proceeds. 


- 


, 
Example: 
& > P I P NENPROG.BAS=COOE.BASrLI r OATA.BASCU1 


Option 
Functton 


W 
Write over files with RO (Read-only) aunbure. Usu- 
ally, if a PIP mmmand tail indudes an existing RO 
file as a destinat~on, PIP sends a quw to the console 
to make sure you want to write over the existing file. 
When this parameter follow. a source name, PIP 
overwrites the RO file without a console exchange. 
If the command tail contains multiple source files, 
this parameter need follow only the last file in the 
list. 


Z 
Zero the parity bit. When this parameter follows a 
source name, PIP sets the parity bit of each data byte 
in the destination file to zero. The source must con- 
tain character data. 
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This command writes the file LONGPAGE.TXT from drive B to the 
printer device. As the file is written, hrm-feed charancrs are removed 
and relnsettcd at the bcgnning and every 65th linc thereafter. 


B > P I P LSTr =PROCRlN.GlSLNTGUI 


This command writs the file PROGRMI.BAS from drive B to the 
printer dev~ce. The N parameter tells PIP to number each linc. The T8 
parameter expands tabs m every eighth column. lblhc U parameter 
translates lower-case letters to uppcr-care as the file is printed. 


This command abstracts a portion of the LETIER.TXT file from drive 
A by searching for the character sequence "Dear Sir" before starting 
the copy operation. When found, the characters arc copied to 
PORTI0N.TXT on drive A until the sequence "Sinccrcly" is found m 
the source file. 


This command copis all filcs with filcrype COM from drive A to drive 
B. Thc V parameter tells PIP to read the datination filer to ensure that 
data was correctly transferred. The W parameter lets PIP ovenvrite any 
dstinatlon filcs that arc marked as RO (Read-only). The R parameter 
tells PIP to read files from drive A that am marked with the SYS (Sys- 
tem) attribute. 


- 
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- The PUT Command 


Synux: 
PUTCONSOLE(OUTPUTT0l FILE hlcrpecllal) 
- 
PUTPRINTER {OUTI'UTTO) FlLF hlcrpec I!oll 
PLrrCONSO1.F (0UIPUTTO)CONSOLE 
PUTPRINTER {OUTPUTTO) PRINTER 
- Explanation: The PUT mmmand is a transient utility that lets you direct console 
output or printer output to a filc. PUT allows you to drrect the system 
to put console output or printer output to a filc for the next system 
- 
command or user program entered ar the console. Or, PUT directs all 
subsequent console or printer output to a filc when you tnclude the 
SYSTEM option. 


Console output is directed to a file until the program terminates. Then, 
console output reverts to the mnrolc. Printer output is directed to a file 
until the program terminates. Then printer output is directed back to 


When you use the SYSTEM option, all subsequent consoldprinter out- 
put is directed to the specified file. This option termmates when you 
enter the PUT CONSOLE or PUT PRINTER command. 


The syntax for the option list is 


[(ECHO I NO ECHO) {FILTER I NO FILTER) I {SYSTEM}] 


Table 5-14 defines the preceding option list. 


- 
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Table 5-14, PUT Ootions 


specifies that the output IS echoed to the con- 
sole. ECHO is the default option when you direct 
console output to a file. 


INo ECHO 
spmfies that the I 
oatput is mot m be echoed 
to the console. 
I 


FILTER 
specifies that filtering of control characters 1s 
allowed, which means that control charanerr 
are translated to printable charamers. For 
example, an escape character is translated to .[. 


N O FILTER 
means that PUT does not rnnslate control 
characters. This is the default option. 


SYSTEM 
specifics that system output and program out- 
put is written to the file specified by filespec. 
Output is written to the file until a subsequent 
PUT CONSOLE command redirects consolc 
oumut back to the console. 


- 


Direct Console Output to a File 


Sptax: 
PUT CONSOLE {OUTPW TO FILE filespec {[o]) 
- 


Explanation: The preceding form of the PUT mmmand tells the system to direct 


subsequent console output to a file. 
- 


Example: 
&>PUT CONSOLE OUTPUT TO F I L E XOUT (ECHO3 


The 
command directs mnrole output to file XOUT with the - 


output echoed to the console. 


- 
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- 
Put Printer Output to a File 


Syntax 
P W PRINTER {OWPW TO} FILE filespec {[o]} 
- 
Explanation: The prcmd~ng form of the P W command directs prtntcr output to a 
file. 


Thc options are the same as in the P W CONSOLE command, except 
that option NO ECHO is the default for the P W PRlNTER command. 
Note that if ECHO is specified, printer output is echoed to the pnnter. 


Exsmpls% 
&>PUT PRINTER OUTPUT TO F I L E XOUT 
R>PIYPROG 


The p 
d 
g 
example d i m the printer output of pmgnm MYPROG 
to file XOW. The output is not echoed to the printer. 


&>PUT PRINTER OUTPUT TO F I L E XOUTZ tECH0,SYSTEMI 


The preceding command directs all printer output to file XOW2 and 
to the pnnter, and the PUT is in effca until you cntcr a PUI PRINTER 
O W P W TO PRINTER mmmand. 


The prlnrrr output can bc drrcacd to one or mom fils. 'lhe output ro 
the* filer tr termtnatd whrn you mvcn prtntcr output to the prlnrer 
using the following command: 


P W PRINTER OWPUT TO PRINTER 


Terminate Console Output to a File 


Syntax 
P W CONSOLE {OWPW TO) CONSOLE 


Explumtion: The preceding form of rhc P W command directs console output to the 


console. 


Example: 
&>PUT CONSOLE OUTPUT TO CONSOLE 


The preceding command directs console output to the console. 
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Terminate Printer Output to a File 


Syntax 
PUT PRINTER (OUTPUT TO) PRINTER 


Explmntion: The preceding form of the PUT command directs the printer output to - 


the printer. 


Example: 
A>PUT PRINTER OUTPUT TO PRINTER 
- 


The preceding example directs printer output to the pnnter. 
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The RENAME Command 
- 


Syntax: 
RENAME {new-filcspec=old-filespec) 
- 
Explmation: The RENAME command lets you change the name of a file that is 
cataloged in the directory of a disk. It also lets you change several 
filenames if you use wildcards in the filespecs. You can abbreviate 
- 
RENAME to REN. 


The ncu filcrpcc mua not hc rhc name of any cxnrrtng file on the d ~ k 
- 
Ihr old.hlr,prc tdcnr~fics an cxlrrlnp hlc ur file, un the d ~ k 


The RENAME command changes the file named by old-filespec to the 
- 
name gtven as new-filespec. 


RENAME doer not make a copy of the file. RENAME changes only 
the name of the file. 


If you omit the drive specifier, RENAME assumes the file to rename is 
on the default dnve. You can include a drive specifier as a part of the 
ncwnamc. If both file specificat~ons name a dnvc, a must be the same 
drive. 


If the file given by oldname does not exist, RENAME displays the 
follow~ng message on the screen: 


N o F i l e 


If the file given by newname is already present in the directory, RENAME 
displays the following message on the screen: 


N o t renamed: f i l e n a m e . t r ~ f l l e s l r e s d v e x i s t s , 
d e l e t e ( Y I N ) ? 


If you want to delete the old file, type Y to delete. Otherw~sc, type N 
to keep the old file and not rename the new file. 


me RENAME Command 
CP/M 3 User's Guidc 


If you use wildcards in the filcrpecs, the wzldcards in the new filerpcc 
must correspond exactly to the wildcard* in the old filcspcc. For exam- 
ple, m the following two commands, the wildcard filespecs correspond 
exactly: 


In the following example, the wildcards do nor match and CP/M 3 
returns an error message. 


A>REN A*. TEX=A. Tr 


knmpla: 
A>RENAMENEUASMIBAS=OLDFILEIBPS 


The file 0LDFILE.BAS changes to NEWASM.BAS on drive A. 


The system prompts for the filespecs: 


E n t e r New N a n e : X . P R N 
E n t e r O l d N a n e : Y . P R N 
Y 
.PRN=X 
. 
PRN 
A > 


File Y.PRN ir renamed X.PRN on drive A. 


B>RENA:X.PAS = Y . P L I 


T h e file Y.PLI changes to X.PAS on drive A. 


The precedmg command renames all the files matching the wildcard 
A'.TEX 
to files wlth filenames matching the wildcard SS.TEX, 


respcmvely. 
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The file OLDLIST changes to NEWLIST on drive B. Because the sec- 
ond drive spectfier, 8: is impltcd by the first, a is unnecessary m th~s 
example. The preccdlng command line has rhe same effect as the 
following: 
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The RMAC Command 


Syntu: 
RMAC filespec {SRd I SSd I SPdJ 


Explanation: RMAC is a relocatable macro assembler that assembles files of type 
ASM into REL hler that can be linked to create COM files. 


The RMAC command options specibj the destination of the output 
frles. The additional specifier d defines the destination drive of the 
output files. A-0 rpec~fies drives A through 0. X means output to the 
console, P means ourput to the printer, and Z means zero output. Table 
5-15 lirn the RMAC command options. 


Table 5-15. RMAC Command Options 


S 
drive for SYM file 
(A-0, X, P, Z ) 


In rhe MAC command, the assembly parameter of H controls the des- 
t~nauon of the HEX file. In the RMAC command this parameter a 
replaced by R, w h ~ h 
conmols the dcst~nation of the REL file; however, 
you cannot direct the REL file to the console or printer, RX or RP, 
because the REL file a nor an ASCII file. 


Exampla: 
A >RPIAC TEST SPX SB RB 


In the preccdcng example RMAC assembles the file TEST.ASM from 
drive A, rends the l~stlng file (TEST.PRN) to the console, pun the 
symbol file (TESTSYM) on drive B and puts the relocatable object file 
(TESTXEL) on drive B. 
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The SAVE Commnnd 


Syntur: 
SAVE 


Explmation: The SAVE command copies rhc contents of memory to a file. To use 
the SAVE utility, first isrue the SAVE command, then run your pro- 
gram which reads a file into memory. When your program exits, it 
exits to the SAVE utility. The SAVE utility prompts you for the filespec 
to which the memory is to be copled, and the beginning and ending 
address of the memory to be saved. 


Example: 
A >S4VE 


The preceding command activates the SAVE utility. Now enter the 
name of the program that loads a file into memory. 


Next, execute the program 


When the program exltr, SAVE rntercepts the return to the system and 
prompts you for the filespec and the bounds of memory to be saved. 


SOVE V e r 3.0 
F l l e ( 0 r R E T U R N t o e u x t I ? d u m ~ 2 ~ ~ 0 0 1 
D e l e t e d u r ~ t . ~ o n 7 Y 
FrosQlOO 
T o ? 4 0 0 


The contents of memory from 100H. hexadecimal, to 400H is copled 
to file DUMPZ.COM. 
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The SET Command 


Syntax: 
SET[options] 
SET d: [options] 
SET filespec [options] 


Explanation: The SET command in~ttates password protection and time stamplng of 


files in the CP/M 3 system. It also sets file and drive annbutes, such as 
the Read-only, SYS, and user-definable attributes. It lets you label a 
dlsk and password protect the label. 


Ihe SET command include options that affect the disk directory, the 
dnve, or a file or ser of files. The discussion of the SET command 
explicitly stares which of the three categories arc affected. 


To enable trme stamping of files, you must first run INITDIR to format 
the disk directory. 


Set File Attributes 


Syntar: 
SET filespec[atrribute-options] 


Explmation: The 
SET command sets the specified attributes of a file or a 
group of files. 


Table 5-16. SET File Amibutep 


Optzon 
Meaning 


DIR 
Sets the file from the SYS directory to the 
(DIR) attribute. 


I 
SYS 
Gives the file the System SYS am~bute. 


1 


Sets the file attribute to allow Read-Only 


XECIS. 


RW 
Sets the file amibute to allow Read-Write 
access. 
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Option 
Meaning 


ARCHIVE=OFF 
Set. the archivc attribute to off. This means 
that the file has not t e n backed up (archived). 
PIP with the [A] option can copy files with 
the archive attribute set to OFF. PIP with this 
option requires an ambiguous file~pec and 
copses only files that have been created or 
changed slnm the last time they were backed 
up w~th the PIP[A] option. PIP then sets the 
archive attribute to ON for each file success- 
fully copied. 


ARCHIVE=ON 
Sets the archive attribute to on. This means 
that the filc has been backed up (archived). 
The archive attrlbun can be turned on 
explicitly by the SET command, or it can be 
turned on by PIP when copying a group of 
filer with the PIP [A] option. The archive 
attribute is displayed by DIR. 


F1 =ONIOFF 
Turns on or off the user-definable filc attri- 
bute F1. 


1 F = O N O F F 
Turns on or off the user-definable file attri- 
bute F2. 


1 F3-ONIOFF 
Turns an a off the user-definable file attti. 
bun F3. 


I F4=ONIOFF 
Turns on or off the user-definable file ami- 
bute F4. 


- 
The preceding command set. MYFILE.TEX to Read-only and System. 


- 
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A > S E T M Y F I L E , TEX CRW D I R J 


The preceding command sets MYFILE.TEX to Read-Wnte with the 
Directory (DIR) attribute. 


Set Drive Attribute 


Syntax: 
SET {d:) [RO] 
SET {d:) [RW 


Explanation: The preceding SET commands set the specified drive to Read-Only or 
Rcad-Write. 


If a drive is set to Read-Only, PIP cannot copy a file to it, ERASE 
cannot delete a file from it, RENAME cannot rename a file on it. You 
annot perform any operation that requires writing to the dak. When 
the specified drive is set to Rcad-Write, you can read or write to the 
disk in that drive. If you enter a CTRL-C at the system prompt, all 
drives are reset to Read-Write. 


Example: 
A>SET B : L R O I 


The preceding command sets drwe B to Read-only. 


Assign a Label to the Disk 


Syotax: 
SET {d:)[NAME=labclnamc.typ] 


Explanation: fie preceding SET command assigns a label (name) to the disk in the 
specified or default drive. 


CP/M 3 provides a facility for crearing a dlrcctory label for each disk. 
The directory label can be assigned an eight-character name and a 
thrce-character type similar to a filename and filetype. Label names 
make it easier to catalog disks and keep track of different disk direc- 
tones. The default label name 1s LABEL. 
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Example: 
A>SET~NAME=OISK1001 


The preceding example labels the dlsk on the default drlvc DISK100. 


Assign Password to the Label 


Synt~lr: 
SET [PASSWORD=password] 
SET [PASSWORD = <cr> 


Explanation: The first form of the precedtng SET command assigns a password to 


the disk label. The second form of the command removes password 
protection from the label. 


You can assign a password to the label. If the label has no password, 
any user who has access to the SET program can set other attributes to 
the disk which might make the disk inaccessible to you. However, ~f 
you asrlgn a password to the label, then you must supply the password 
to set any of the functions controlled by the label. SET always prompts 
for the password rf the label is password-protected. 


Examples: 
A>SETCPASSWORO=SECRETI 
A>SET CPASSWORO=<er> 


The first command asstgns SECRET to the disk label. The second com- 
mand nullifies the existing password. 


Note: If you use password protection on your dirk, be sure to record 
the password. If you forget the password, you lose access to your dirk 
or filer. 


Enahle/Disable Password Protection for Files on a Disk 


Syntax: 
SET [PROTECT = ON] 
SET [PROTECT= OFF] 


Explnnntion: The first form of the SET command turns on password protectloo for 
- 
all the files on the disk. T h e password protection must be ~ r n e d 
on 
before you can assign passwords to individual files or commands. 
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The second SET command daables password promiion for the files on 
your dirk. 


Aher a password is assigned to the label and the PROTECT option is 
turned on, you are ready to assign passwords to your filcs. 


You can always determlnc ~f a disk is password-proteaed by using the 
SHOW command to display the label. 


Assign Passwords to Files 


Synr~x: 
SET filespec[PASSWORD=password] 


E x p h a t i m The preceding SET command sets the password for filespec to the pass- 
word indicated ~n the command tail. Passwords can be up to eight 
characters long. Lower-case lmers arc translated to upper-care. 


You can use wildcards in the filespec. SET assigns the specified pss- 
word to the files that match the wildurd-filespec. 


Note: alwavs record the oasswords that vou assien to "our files. 
. 
- 
. 


Without the oassword. vou cannot a-s 
tho= files unlcaa ~arrword 
. , 


prorrman fir turned off for the whole dirk I1 you forger the password 
to the directory label, you cannot rum off the password protcmon for 
the disk. 


Example: 
&>SET MYFILE. TEXlP4SSWORD;MYFILJ 


MYFlL is the password assigned to file MYFILE.TEX 


Set Password Protection Mode for Files with Passwords 


Syntax 
SET filespec [PROTECT=READ] 
SET filespec [PROTECT= WRITE] 
SET filespec [PROTECT=DELETE] 
SET filespec [PROTECT=NONE] 


- 
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Explanation: You can assign one of four modes of password protection m your file. 
The ~rotection modes are READ, WRITE, DELETE, and NONE and 
are described m yhe following table. 


Table 5-17, Password Protection Modes 


ode 
1 
Protection 


READ 
The password is required far reading, copying, 
writing, deleting, or renaming the file. 


WRITE 
The password is required for wnting, deleting, or 
renaming the file. You do not need a password to 
read the file. 


DELETE 
The password is only required for delering or re- 
naming the file. You do not need a password to 
read or modify the file. 


NONE 
No password adsa hr the Me. If a paword aurts, 
this modifier can be used to delete the password. I 


Assign a Default Password 


Syntax: 
SET [DEFAULT=password] 


Explaration: The preceding set command assigns a default password for the system 
to use during your computer session. The system uses the default pass- 
word to access password-protected files if you do not specify a pars- 
word, or if you enter an incorrect password. The system lets you access 
the file if the dehult password marches the password asslgncd to the 
file. 


Example: 
B>SET r . TEXCPASSIJORO=SECRETr PROTECT=URITEl 


The preceding command assigns the password SECRET to all the TEX 
files on drive B. Each TEX file is given a WRITE protect mode to 
prevent unauthorized editing. 


The SET GMnnnd 


Eumplc: 
R>SETLDEFCIULT=ddl 
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- 


The preced~ng command instmm the system to use dd as a password 
if you do not cntcr a password for a password-protected file. 
- 


Set Time Stamp Options on Disk 


Sptnx: 
SET [CREATE=ON] 
SET [ACCESS = ON] 
SET [UPDATE= ON] 


Explanation: The preceding SET commands allow you to keep a record of the time 
and date of filc creatlon and update, or of the last access and update of 
your files. 


[CREATE=ON] 
turns on CREATE time stamps on the disk in 
the default drive. To m r d the cmtcon time 
of a file, the CREATE optlon must have been 
~ r n e d 
on before the file is created. 


[ACCESS=ON] 
NmS on ACCESS time stamps on the disk in 
the default drive. ACCESS and CREATE 
options are mutually exdunvc. Tbk means that 
only one can be in effect at a time. If you Nm 
on the ACCESS tlmc stamp on a disk that has 
the CREATE time stamp, the CREATE time 
stamp is automatically ~ r n c d 
off. 


[UPDATE=ON] 
tums on UPDATE time stamps on the disk in 
the default drive. UPDATE rime stamps rcc- 
ord the tlme the file war last modified. 


To enable time stamping, you must first run INlTDIR m format the 
disk directory for time and datc stamping. 


Although there are t h m kinds of date/time stamps, only two dateltime 
stamps can be asroaated with a given file at one tme. You can choose 
to have either a CREATE datc or an ACCESS datc for files on a oartlc- - 
ular disk. 


- 
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Whm you set both UPDATE and CREATE time stamps, notice that 
editing a file changes both the UPDATE and CREATE time stamps. 
This is because ED does not update the original file but creates a new 
version wlth the name of the or~glnal file. 


The DIR with [FULL] option displays the following date and time 
stamps: 


N.l. 
BY,.. 
R.0, 
P l t t r r b ~ l l l P l o t 
UId.,. 
A c e e r l 
............................................................... 


ONE 
STEX 
91 
71 
D l r RU 
Nonr 
08/03/81 LO156 


THREE 
.TEX 
l t l l 
SS 
D1,RY 
None 
08/05/81 
LS:45 


TYO 
.TEX 
101 
76 
0x1 RU 
None 
OBllOlSl 09:LJ 


The access ume stamps displayed show the time the file war last dis- 
played or edited. Note that displaying a filename in a dxrectory listing 
docs not constl~te an access and a not recorded. 


The hllowmg DIR output below shows how files with create and update 
time stamps are displayed. 
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Additional SET Examples 


We preceding setting gives the most protection for all the COM files on 
drive A. With the password protection mode set to READ, you cannot 
even read one of the COM files without entering the password 123, 
unless the default password has bnn set to 123. Even if the correct 
password is entered, you still cannot write to the file because the file is 
Read-Only. 


The preceding mmmand reverses the protcctlon and access attributes of 
the COM files affected by the previous example. After executing the 
preceding command, there is no password protection, the files of type 
COM can be read from or written to, and are set to DIR files. 
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- The SETDEF Command 


Syntax 
SETDEF(d:{,d:{,d:(,d:)}}}WMPORARY =d:] I [ORDER=(typ{,rypR]} 
- 
SETDEF [DISPLAY I NO DISPLAY] 
SETDEF [PAGE I NO PAGE] 


- Explanation: The SETDEF command Ins you display or define the disk search order, 
the temporary dnvc, and the filetype search order. The SETDEF dcfini- 
tions affect only the loading of Dromams andlor exccurion of SUBMIT 
(SUB) files. T~~SETDEF 
command aimlets you turnodofftheDlSPLAY 


and PAGE modes for the svstem. When DISPLAY mode is on. the svstem 
. . 


dls~lavs 
the location and name of oroeramr loaded or SUB files executed. 
PAGE mode is on, CP/M j uzities stop aker displaying one full 
screen of information. P 
~ 
E 
any key to continue the display. 


The system usually searches the specified drive or the default drive for 
filcs. The user can use the SETDEF command, to u v n d the search for 
program files and submit file, far execution purposes only. 


Note: A CP/M 3 program file has a filetype of COM. A file containing 
commands to be executed by SUBMIT has a filetype of SUB. 


Display the Program Loading Search Definitions 


Syntax: 
SETDEF 


Explanation: The preceding form of the SETDEF command displays the drsk search 
order, the temporary drive, and the filctype search order. 


Assign the Drive for Temporary Files 


Syntax: 
SETDEF [TEMPORARY =D:l 


Explanation: The preceding form of the SETDEF command defines the disk drive to 


be used for temporary filcs. The default drive used for temporary filer is 
the system default dnvc. 


C DlClTAL RESEARCH'" 


5-95 


nlhc SETDEF Command 
CP/M 3 U8rr.r Guide 


Example: 
A>SETDEF lTEMPORARY=C: J 


The preceding command sen disk drive C as the drive to be used for 
temporary files. 


Define the Disk Drive Search Order 


Syntax: 
SETDEF { d: {,d: {,d: {,d:)))} 


Explanation: The preceding form of the SElDEF command defines the disks to be 


searched by the system for programs andlor submit files to be executed. 
The CP/M 3 default is to search only the default dnve. 


Note: ' can be substituted for d: to indicate that the default drive is 
to be included m the drive search order. 


Example: 
A>SETDEF C : +r 


The preceding example tells the system to search for a program on drive 
C, then, ~f not found, sear& for it on the default drive. 


Define the Filetype Search Order 


Syntax: 
SETDEF [ ORDER = (ryp (,rypl) I 


where ryp = COM or SUB 


Explanation: The preceding form of the SETDEF command defines the filetype search 


order to be used by system for program loading. The filetype, lndtcatcd 
as ryp in the syntax line, must be COM or SUB. The CP/M 3 default 
search is for COM files only. 


Example: 
A>SETDEF IDRDER=(SUB 1CDMJJ 


The preceding command instructs the system to search for a SUB file to 
execute. If no SUB file 1s found, search for a COM file. 
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Turn OnfOff System Display Mode 


Syntax 
SETDEF [DISPLAY I NO DISPLAY] 


Fxplmetion: The prcmdlng command mms the system display mode on or off. Ihe 


default system display modc is off. When the display modc 1s on, 
CP/M 3 d~splays the following informarlon about a program file before 
loading it for execution: dnve, filename, filetype (sf any), and user number 
(if not the default user numbcr). 


Example: 
&>SETDEF CDISPLaYI 


The preceding command turns on the system display made. The system 
now displays the name and location of programs loaded or submit files 
executed. For example, rf you enter the PIP command after turning on 
the system display mode, CP/M 3 displays the following: 


& > P I P 
& : P I P 
COM 


CP/M 3 P I P VERSION 3 . 0 


~ndncrtmg that the file PIP COM war loadcd from dr~vc A under rhc 
current uscr numhcr. If the currcnt user numbcr Is not 0, and ~f PIP C041 
does not exist under the current uscr numbcr, then the system drsplays 
the location of PIP.COM as follows: 


indicating that PIP.COM was loadcd from drive A under user number 
0. This mode is m effect until you enter 


to Nm off the svstem DISPLAY mode. 
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Syntax: 
SETDEF [ PAGE( NO PAGE ] 


Explenation: The preceding command turns onloff the system page modc. When the - 
PAGE mode 1s set to on, CP/M 3 utilities stop after displaying one 111 
screen of mformatlon. called a console DaEe. The utllitnes resume aker 
. - 


you pras any key. 


The default setting of the system page mode is ON. 


Exmple: 
0)SETDEF [ N O PACE1 


The prcced~ngrommandmrnr off the rysrcm page modc. CP M 3 utnlmt~cr 
do not pause ahcr d,rplay~np a full conrole pagc. but conrnnur to vroll - 
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The SHOW Command 


Syntur: 
SHOW {d:X[SPACE ILABEL IUSERS IDIR IDRIVE]) 


Explanation: Ihe SHOW command displays the following dirk drtve information: 


access mode and amount of free disk space 
I disk label 
current user number 


1 number of files for each user number on the disk 
1 number of free dirccmry ennies for the disk 


drwe characteristics 


Display Access Mode and Disk Space Available 


Syntax 
SHOW {d:X[SPACE]} 


!2qlanation: The preceding form of the SHOW mmmand displays the dnve, the access 
mode for that drive, and the rrmainingspace in kilobytes for the specified 
drive. SHOW by itself displays the information for all logged-m drives 
in the system. 


- Examples: 
A>SHOW 6 : 
0 : RWI Space: 
9.488K 


A >SHOW 
A: R W t S P ~ C ~ : 
4 K 
- 
0 : R W I Space: 
9,488K 


The first cxamplc rhowr that drwe B has Rcad Wntc acccw and ~r has 
9,488K b)rcr of space Ich Ihc second cxarnplc shows that drtvc A also 


IS Kcad Wrnrc and has only 4K bytes Ich and drwr B IS Read-Wnre and 
has 9,488K bytes left. 
- 


Display Disk Label 
- Synt5: 
SHOW {d:)[LABEL] 


Explanation: T h e p d n g f o r m of the SHOW mmmanddisplayadisklabel information. 
- 
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The preceding command displays rhc following for drwe B: 


D 
o 
a 
d 
Stam. 
SI~IF 
Label C118lsd 
Lab11 U l d a t s d 


Label 
R e ~ d 
C1ea1. Updatc 
.......... ..-.--. ...... -..-.. -----...--.-.- 
----.--------. 


T0MSDISI. 
on 
a n 
on 
07104181 10130 07/08/81 09~30 


The first column, directory label, displays the name assigned to thar 
drive directory. The second column, Parswds Reqd, shows thar pass- 
word protection has been turned on for that dnvc. 


As described in the SET command, each file can have up to two timc 
stamps. The first of these tlme stamps can be either the creation date 
and time for the file or the date and time of the last access to the filc. 
Access IS defined as reading from or writing to the file. The third 
column of the SHOW [LABEL] ourput displays both the type of stamp 
and whether or nor it is on. In the preceding example, creation time 
stamps are vven to new fils as shown by the stamp crestc column 
heading. 


The fourth column displays the status of the second time stamp field, 
the update timc stamp. Update time stamps display the date and tlmc 
of the last update to a filc, that IS, the last timc someone wrote to the 
file. In the SHOW [LABEL] display, update tlme stamps are ~ m c d 
on. 


Ekwdcr rhowlng rhc password prorcctlon and rhc annc tmmr stamp, on - 


r dnvr, SHOE' [LABEL' rl-o dnplavr rhc dare and rlmr ,hat rhc label 
was mated and last updated. 
- 


Display User Number Information 


Syntax: 
SHOW {d:)[USERS] 
- 


Explanation: The preceding command displays the current user number and all the 
users un clrc dnve and the mrrespondtng number of files =$signed to - 
them. 
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Emmple: 
A>SHOU LUSERSJ 
a c t i v e U s e r : 
1 


Actlue F l l e s : 
0 
2 
3 
4 


a: 
o f f i l e s : 
95 
4 0 
1 
26 
A: 
Number o f f r e e d > r e c t o r r e n t r i e s : 350 
A > 


Display Number of Free Directory Entries 


Syntax: 
SHOW {d:}[DIR] 


Explanation: The preceding command displays the number of free d~rectory entries 


cn the specified drive. 


C : Number of f r e e d i r e c t o r y e n t r i e s : 24 


The preceding command shows that there are only 24 free directory 
entries on drive C. 
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Display Drive Characteristics 


Syntax: 
SHOW {d:)[DRIVE] 


Explanation: The 
form of the SHOW command displays thcdrive charac- 
teristics of the specified drive. 


Example: 
R>SHDW [ D R I V E 1 


The following a an example of the system display for the preceding 
command: 


A: Drive Characteristics 
3,600: 128 Byte Record Capacity 


450: Kilobyte Drive Capacity 


96: 32 Byte Directory Entr~es 
96: Checked Directory Enrrtcs 


128: Records / Dtrectory Entry 
16: Records / Block 
48: Sectors / Track 
512: Bytes 1 Phystcal Record 
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Synux: 
SID (pgm-fikspec} {,sym-filapcc) 
- Erplaltetioll: The SID (Symbolic Instruction Debugger) allows you to monitor and 


test programs developed for the 8080 microprocessor. SID ruppons 
- 
real-time breakpoints, fully monitored executxon, symbolic deassembly, 
assembly, and memory display and fill functions. Utility programs are 
supplied with CP/M 3 that can be dynamically loaded with SID to 
provide traceback and histogram facilities. 


SID commands display memory and CPU regsters and direct the break- 
point operations durlng the debuwng session. 
- 
Without a file svecification SID loads into memaw without a test vro- 
gram. Use this iorm to uamine memory or to write and test simple 
programs using the A command. You must nor use the SID commands 
G, T, or U, described later, until you have first loaded a rest program. 


A SID command line with a om-filesnec loads both SID and the t e r 
.- . 


oroeram mm memorv. If the f i l m c is omitted from the filesocc. COM 
7 .. 
. 
. 
~ 


s assumed. SIL) opnonally load. ~n a symbol table file spcoficd by ,ym- 
filoprc. The rym-61rrpcc nccd, no filcrypc because FlD looks for a file 
wlrh filnypc SYM Cle the C, G, T, or U command I#, hcgn exerutlon 
of the test program under supervision of SID. 


Use CII(L-S to halt the screen display. CTRL-Q restarts the display. 
Abort lengthy displays by typing any keyboard character. Use CTRL-C 
to exit from SID. 


SID can address absolute memory locations through symbolic expres- 
stons. A symbolic expression evaluate to either an address or a data 
item. 


SID ~ o m r n d 
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A symbol~c cxprcrrmn can be a name from a SYM filc produced from 
your program bv a CP M Macro Arrcmblcr. When you prcccdr thc 
rymbol~r cxprcrr~on with a pcrtod, SlD returns as addrrrr m hcxadccn- 
mal. When you precede the symbolic exprcsslon with the at sign, @, 
SID returns the 16-bit value stored at that location and the next cantla- 
uous locadon. When you precede the symbolic expression wth an equ> 
sign, SID returns the &bit value stored at that location. For two-byte 
expressions, this is the low byte because the 8080 mxcromocessor stores 
th; low value of a two-byte word first. 


A symbolic expression can be a literal value m hex, decimal, or ASCII, 
as indicated in the following list: 


SID uses literal hex values as given, but truncates any digits in 
excess of four on the left. The leftmost digit is the most significant 
digit. The rightmost digit is the least significant digit. 


1 To indicate decimal values precede them with a pound sign, #. 


D ~ ~ i m a l 
values that evaluate to more than four hex digits arc eval- 
uated as the modulo of 
hex value FFFF. For example, 


X65.534 = FFFEH, while X65.536 =0001H. 


1 SID translates literal ASCII character strings between apostrophes 


to the hex value of the two rightmost ASCII characten. 


You can combine symbolic cxpresslons with the symbohc operators, + 
or -, to produce another symbolic expression. Symbolic expressions 
combined in this way can be used to calculate the offset of an lndtrenly 
addressed data aem, for example a subscripted vanable. A special up- 
arrow operator, ^, can reference the top-of-stack item. A strmg of n . 
operators can reference the nth stack item without changing stack con- 
tent or the stack pointer. 


Table S - l b Ihrrq rhr SlD commands wnrh their mrrerpondmnp parame. 
rcrs and optnonr. The s ~ a l 
command lrncr I, pnntcd m boldface. Thc 


parameter- arc ~n lower-are md follow [he mmmand Icncr. Opnunal 
items are in braces. Replace the arguments with the appropriate sym- 
bolic expressions as hsted. Where two symbolic expressions are needed, 
SID can calculate the second one ftom the first ustng the symbolic 
operators described previously 
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Table 5-18, SID Commands 
- 


1 
Name 
I 
Svntm 
I 
Meaninr 
1 


Assemble 


Call 


Display 


Load 


Load 


Fill 


Go 


Hex 


lnput 


List 


lcommand tail 


L ls)bfl 


Entcr assembly language statements. s is the sran 
address. 


Call to memory locarion from SID. s is the called 
address, b IS the value of the BC register pair, 
and d rs the value of the DE register pan. 


Display memory in hex and ASCII. W specifies 
a 16-bit word format, s is the start address, 
and f is the finish address. 


Load program and symbol table for execution. 


Load a symbol table file. 
I 


Fill memory with constant value. s is the start 
address, f is the finish address, and d is an 8- 
b ~ t 
data item. 


Brgm rxcrutlon p Ir a rtrn addre,,, a nr a trm 
porary bmakpo~nt, and h nr a qccond tempo. 
rary bmokponnt GO rx~tr SID hy prrrorrnong a 
warm boot. 
I 


D~splays all symbols with addresses in hex. The 
first syntax displays hex, dectmal, and ASCII 
values of a. The second syntax performs num- 
ber and character conversion, where a is a sym- 
bolic expression, and the third syntax com- 
putes hex sum and difhrence of a and b, where 
a and b are symbolic expressions. 


lnput CCP command line. 
I 


List 8080 mnemonic instructions. s is the start 
address. and f is the finish address. 
1 


- 
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I 
tlnatik start address. 
I 


Table 5-18, (continued) 


1 a 
d 
~ ~ ~ u p e c { , d i ad cwie/symbo~c. d is m offset a each 


address. 


- 
- 


Name 


Pass pomt set, reset, and display. p is a perma- 
P'*'c'J 


nent breakpoint address, and c is initial value 
of pass counter. 


W k 
Set memory valuer. s is an address where value 
is wnt, W is a 1Cbit word. 


- 


Trace 
T{n{,c)} 
T a c t program execution. n is the number of 
program sups, and c is the utility entry addrczs. 


Move 
Ms,h,d 
Move memory block. s is the start address, h is 
the h i d address of the block, and d a the des- 


Syntrv 


Trace 
T(W){n{,c)) 
Trace wthout call. W insrmca SU) not m tna 
subroutines, n 1s the number of program steps, 
and c 1s the utilq entry address. 


Meaning 


Untrace 
Um{n{,c)) 
Monimr aecutlon without trace. n s the num- 
ber of program steps, c is the utility entry 
address, W tnstructs SID not to trace 
subroutines. 


Value 
V 
Display the value of the n u t available location 
in memory (NEXT), the next location aker the 
largest file read in (MSZE), the current value of 
the program counter (PC), and the address of 
the end of available memory (END). 


Write 
Wfilespec{,s,O 
Write the contents of a contiguous block of 
memory to filespec. s is the start address, f is 
the finish address. 


Examine 
X{f){r} 
Examinelalter CPU state. f is flag bit C, E, I, 
M. or Z; r 1s register A, 8, D, H, P or S. 
- 
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In the preced~ng example CP/M 3 loads SID from drive A into memory. 
SID displays the # prompt when it is ready to acapt commands. 


A > B : S I D SlnPLE,HEX 


In the preceding example, CPIM 3 loads SID and the program file 
SAMPLE.HEX into memory from drivc B. SID daplays: 


NEXT 
MSZE 
PC END 
nnnn 
mmmm pppp 
eeee 


In the preceding example, nnnn is a hexadecimal address of the next 
free location following the loaded program, and mmmm is the next 
locauon after the largest program. This is rn~tially the same value as 
NEXT. pppp is the initial hexadecimal value of the the program coun- 
ter. eeee 1s the hexadecimal address of the logical end of the TPA. 


XDFEOO+r128+5 


In the preceding example the first pound sign, #, is the SID prompt. 
This SID command, D, displays the values stored in memory start- 
ing at address FE80 (FEOO + #128) and endlng at address FE8S 
(FE80 + 5). 


sm Utilities 


The SID utilities HIST.IJTL and TRACE.IJTL are special programs that 
operate with SID to provide additional debudng facilities. The mech- 
anlsms for system initialization, data colleaion, and data display arc 
described m the CPIM SID" Symbok Instruction Debugger User's 
Guide. The fallowing discussion illustrates how a uuhty is amvated. 
You load the utillty by naming ~t as a parameter when invokmg SID: 


SID filename.UTL 


In the preceding example filename is the name of the utility. Following 
the initial sign-on, the utility can prompt you for additional debugging 
parameters. 


7 
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The HlST utility mates a histogram (bar graph) showing the relative 
frequency of execution of code w~thin sdectcd program segments of the 
test program. The HIST utility allows you to monitor those sections of 
code that execute most frequently. 


Upon stan-up HlST prompts 


TYPEHISTOGRANBOUNDS 


Enter the bounds in the following format: 


aaaa,bbbb 


for a histogram between locauons aaaa and bbbb inclusive. Collect 
data in U or T mode, then display mults. 


The TRACE utility obtains a maceback of the instructions that led to a 
particular breakpoint address in a program under teat. You can collect 
the addresser of uo to 256 instructions between oass ooints in U or T 
. . 
modes. 
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The SUBMIT Command 


Syntax 
SUBMIT filespec) {argument) ... {argument) 


Elrphnntion: The SUBMIT command lets you execute a group or batch of com- 


mands from a SUB file, which is a file with filetype of SUB. 


Usually, you enter commands one line at a time. If you must enter the 
same sequence of commands several times, you might find it easler to 
batch the commands together using the SUBMIT command. To do this, 
create a file and enter your commands in thls filc. The file is identified 
by the filename, and must have a filetype of SUB. When you issue the 
SUBMIT command, SUBMIT reads the file named by the filespec and 
prepares it for interpretation by CP/M 3. When the preparation is com- 
plete, SUBMIT sends the file to CP/M 3 Ime-by-line, as ~f you were 
w i n g each command. 


We SUBMIT command executes the commands fmm a SUB file as if 
you are entering the commands from the keyboard. 


You create the SUB filc with the ED utility. It can contain CP/M 3 
commands, nested SUBMIT commands, and input data for a CP/M 3 
command or a program. 


You can pass arguments to SUB files when you execute them. Each 
argument you enter a assigned to a parameter in the SUB file. The first 
argUmFnt replacer every occurrence of $1 in the file, the second argu- 
ment replaces parameter $2, ctc., up to parameter 59. For example, if 
your file START.SUB contains the follow~ng commands: 


ERA $l.BAK 
DIR $1 
PIP $1 = A:5Z.COM 


and you enter the following SUBMIT command: 


A>SUBNIT START SAM TEX 
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the argument SAM is substituted for every $1 m the STARTSUB file, 
and TEX for every occurrence of $2 m the START.SUB file. SUBMIT - 
then creates a file with the parameter substitutions and executes this 
file. This file now contains the following commands: 


ERA SAM.BAK 
DIR SAM 
PIP SAM=A:TEX.COM 


If you enter fewer arguments in the SUBMIT command than parame 
ten in the SUB file, the remaining paramcnn are not included in the 
commands. 


If you enter more argummrs in the SUBMIT mmmand than parameters 
m the SUB file, the remaining arguments are ignored. 


To Indude an actual dollar sip, S m your SUB file, type two dollar 
signs, $$. SUBMIT replaces them with a single dollar sign when it 
substitutes an argument for a parameter in the SUB file. For example, 
if file AA.SUB contams line: 


MAC $1 $$I2 


and you enter the following SUBMIT command: 


PI>SUBMIT AA ZZ SZ 


then the translated file contains the following: 


MAC ZZ $SZ 


Program Input Lines in a SUB File 


A SUB file can contain program input lines. Any pmgram input is 
preceded by a less than sign, <, as in the following example: 


P I P 
<B:=*.ASM 
<CON:=DUMP.ASM 
< 
D I R 
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The three lines aher PIP arc input lines m the PIP command. The third 
hnc cons~sa only of the < sgn, indicating a carriage m m . The car- 
riage return causes PIP to return to the system to execute the final DIR 
mmmand. 


If the program mminaa More using all of the input, SUBMIT ignom 
the excess input lina and displays the following warning message 


U a r n x n l : P r o b r a . i n p u t i Y n o r c d 


If the program requires mom input than is in the SUB file, it expects 
you to enter the remaining input from the keyboard. 


You can enter control characters in a SUB file by using the usual mn- 
vcnnon of prcmdtng rhr control character bv an up-anow character, 1, 
followed by the lrncr to bc convened to a control charancr To mtrr 
an amal 1 charancr, use rhc mmb~nat~on 
I1 Thlr combmanan trans- 
late~ 
to a single 1 m the same manner that $$ translates to a single $. 


The SUB File 


The SUB file can contain the hllowrng types of lines: 


Any valid CPlM 3 command 
Any valid CPlM 3 command with SUBMIT parameters 


1 Any data input line 
Any program input line with parameters ($0 m $9) 


CP/M 3 command lines cannot ucecd 128 characters. 
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Example: 
The following liner illustrate the variety of lines that can be entered in 
a SUB file: 
- 


D I R 
D I R *sBAK 
MAC $ 1 5 1 1 4 
P 1 P L S T : = $ 1 1 P R N t T 5 2 5 3 1 5 1 
D I R *.ASM 
P I P 
<B:=*.RSM 
<CON:=DUMP.ASM 
< 
D I R B : 


Executing the SUBMlT Command 


Syntax: 
SUBMIT 
SUBMIT filespec 
SUBMIT filespec argument ... argument 


If you enter only SUBMIT, the system prompts for the rest of the 
command. You enter the filespec and arguments. 


Example: 
A >SUBMIT 


Ihe system displays the fallowing prompt. Enter filespec and arguments 
here, such as: 


E n t e r F i l e t o S u b m i t : S T A R T 6 TEX 


Another example could be 


Sull another example using parameters is 


A > S U B N I T A A ZZSZ 


where AA is the SUB file AA.SUB, Z Z is the argument to replace any 
occurrences of $1 in the AA.SUB file and SZ is the argument to replace 
all occurrences of $2 in the AA.SUB file. 


The PROFILE.SUB Stan-up File 


Every rime you turn on or reset your computer, CP/M 3 automaucally 
looks for a specla1 SUB file named PROF1LE.SUB to execute. If it does 
not exist, then CP/M 3 resumes normal operation. If the PROFILE.SUB 
file exists, the system executes the commands m the file. This file a 
convenient to use if you regularly execute a set of commands before 
you do your regular session on the computer. For example, if you want 
to be sure that you always enter the current date and time on your 
computer before you enter any other commands, you can create the 
PROFILE.SUB file, with ED, and enter the DATE command as follows: 


DATE SET 


Then, whenever you bring up the system, the system executes the DATE 
command and prompts you to enter the date and time. By using this 
facility, you can be sure to execute a regular sequence of commands 
before stanlng your usual session. 
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The TYPE Command 


Syntax: 
TYPE {filespec {[PAGEII[NO PAGEln 


Explanation: The TYPE command displays the contents of an ASCII character file 
on your screen. The PAGE option displays the console listing in paged 
modc, whlch means that the console listing stops automatically after 
lisrine n lines of text. where n is usuallv the svstem default of 24 liner 
per page ,kc 
the DEVICE command to set n ro a ddfcrcn~ value.) 


Prnr any character to Lontlnve lhrrnng another n Imr, of rcxt. Prcrr 
<-I KL.C t o rxlt back to the svrrcm. PAGE Is the default modc. 


The NO PAGE optlon displays the console listing continuously. 


If you do not enter a file spec~fication in the TYPE command the system 
prompts for a filename with the message: 


E n t e r f i l e n a m e : 


Respond with the filespec of the file you want listed 


Tab characters occurring in the file named by the file specification are 
expanded to every eighth column position of your screen. 


At any time during the display, you can interrupt the Itsting by pressing 
CTRL-S. Pmr CTRL-Q to resume the Insting. 


Press CTRL-C to exit back to the system. 


Make sure the file specification identifies a file containing character 
data. 


If the file named by the file specification is not present on the specified 
drive, TYPE displays the following message on your scmm: 


No F i l e 


CP/M 3 User's Guidc 
The TYPE Command 


To list the filc at the prlntcr and on the screen, type a a 
- 
P 
before 


entering the TYPE command line. To stop echomg console output at 
the printer, type a second CTRL-P. The type command displays the 
contents of the file until the sueen is filled. It then pauses until you 
press any key to conttnuc the display. 


Examples: 
A > TYPE MYPROC. P L I 


This command displays the contents of the filc MYPROG.PL1 on your 
screen, a page at a time. 


This command continuously displays the contents of the file THISFILE 
from dr~ve B on your screen. 
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The USER Command 


Syntax: 
USER Cumber) 


Fxplmation: The USER command sets the current user number. When you start 


CP/M 3, 0 a the current user number. You can use a USER command 
to change the current user number to another in the range 0-15. 


CP/M 3 identifies every file with a user number. In general, you can 
access only files ~denttfied wlth the cumnt user number. However, ~f 
you mark a file m user 0 with the SYS annburc, the file can be accessed 
kom all other user numbers. 


We system command pmmpts for the user number, as follows: 


E n t e r U r e r r : 5 
50 > 


We current user number is now 5 on drive A. 


A>USER 3 
3 R > 


This command changer the current user number to 3. 


- CP/M 3 Usa'r Gurdc 
The XREF Commnnd 


The XREF Command 


Syntax: 
XREF (d:) filename ($PI 
- 


, 
Explanation: The XREF command provides a cross-reference summary of variable 
usage in a program. XREF requires the PRN and SYM file produced 
- 
by MAC or RMAC for the program. 


'Ihe SYM and PRN filer must have the same filename as the filename 
- 


in the XREF command tad. XREF outputs a file of type XRF. 


Examples: 
A >XREF b:PIYPROG 


In rhls cxamplc. XKEF 1, on dnvc A XREF opcrarrr on rhc filc 
MYPR0G.SY.V and MYPROG PRY whxh arc on dr~vc B. XRFF pro- 
duce. rhc file .UYPROG.XRF on drlvc B. 


In the preceding example, the $P option directs output to the printer. 


End of Section 5 
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- 
Section 6 
ED, The CP/M 3 Context Editor 
- 


6.1 Introduction to ED 
- 
To do almost anything with a computer you need some way to enter data, a way 
to give the computer the information you want it to process. The programs most 
commonlv used for this task arc called editon. They transfer "our kevstrokes at the 
keyboard'to a disk file. CP/M 3's editor is named ED. using ED, ;ou can easily 
create and alter CP/M 3 text files. 


The correct command format for invoking the CP/M 3 editor is gven in 
Section 6.2, "Starting ED." After starting ED, you issue commands that transfer ten 
from a disk file to memory for editing. Section 6.3, "ED Operation," details this 
operation and describes the basic text transfer commands that allow you to easily 
enter and extr the editor. 


Section 6.4, "Basic Editing Commands," details the commands that cdit a file. 


Section 6.5, "Combining ED Commands," describes how to combine the basic com- 
mandr to cdit more efficiently. Although you can edit any file with the basic ED 
commands, ED provides several more commands that perform more complicated 
editing functions, as described in Section 6.6, "Advanced ED Commands." 


During an editing session, ED can return nvo type of error messages. Section 6.7, 
"ED Error Messages," lisn these messages and provides examples that indicate how 
to recover from common editing error conditions. 


Syntax: - 


ED input-filespec {d: I ourput-filespec) 


To start ED, enter its name after the CP/M 3 prompt. Ihe command ED must be 
followed by a file spec~ficat~on, 
one that contarns no wildcard characters, such as: 


A>ED MYFILE, TEX 
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The file soecification. MYFILE.TEX m the orccedine examole. soecifics a file to be 
~ - 
~7 
" 
. . . 


cdnrcd ur created 'Ihc file \pcc~ficarnon can be prrccdcd hv a drtvr rpecrfiiar~on, but 
a drmvc $pccmficat~on nr unncccrrary ~f the file to be rdmtcd Is on your default drtve 
Optionally, the file specification can be followed by a drwe specification, as shown m 
the following example: 


In response to rhls command, ED opens the file to be edited, MYFILE.TEX, on 
drive A, but sends all the edited material to a file on drive B. 


Optionally, you can rend the edited material to a file with a different filename, as 
in the following example: 


&>ED MYFILE, TEX YOURFILE. TEX 


The file with the different filename cannot already exist or ED prints the following 
message and termmates. 


O u t ~ u t F i l e E x i s t s . E r a s e I t 


The ED prompt, ', appears at the screen when ED is ready to accept a command, 
as fol!ows 


A>ED MYFILE, TEX 


: * 


If no previous version of the file exists on the current disk, ED automatically 
creates a new file and displays the follow~ng message: 


NEW F I L E 
: 


Note: before stantng an editing session, use the SHOW command to check the 
amount of free space on your dlrk. Make sure that the unused portion of your disk 
is at least as large as the file you arc editing, or larger if you plan to add characters 
to the file. When ED finds a disk or directory full, ED has only limited recovery 
mechanems. These are explalncd in Section 6.7, "ED Error Messages." 


- 
6.3 ED Operation 


Wlrh ED. you change porttons of a file that pars through a mcmory hufkr. When 


you rran ED s n h one of the prrcrdtng command^, thtr mcmory buffcr s rmpq Ar 
- 
"our mmmand, ED reads scgmcnrr of the source file, for cxnmplc HYFII F.TEX, 
into the mcmory buffer for you to eda. If the file is new, you must insert text into 
the file before you can edit. During the edit, ED writes the cdltcd t a t onto a temp- 
- 
rary work file, MYFILE.$$$. 


When you end the edit, ED writes the mcmory buffer contents to the temporary 
- 
file, followed by any remamng twt in the source file. ED then changes the name of 
the source file from MYFILE.TEX to MYFILE.BAK, so you can reclaim this onmnal 
material from the back-up file d necessary. ED then ienames the tempraifile, 
MYFILE.$$$, to MYFILE.TEX, the new edited file. The follow~ng figure illustrates 
- 
the relationship between the source file, the temporary work file, and the new file. 


Note: when you invoke ED with ovo filespen, an input file and an output file, ED 
- 
docs not rename the input file to type BAK; themfore, the input file can be Read- 
Only or on a write-protected dirk if the output file IS written to another disk. 


- 
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MYFILE. $$$ 


I 


AFTER I 


EDIT I IE' 


I 
INSERT 


I 


MYFILE. TEX 


BACKUP 


MYFILE BAK 


Figure 6-1. Overall ED Operation 
- 


In the receding figure, the memory buffer is logically between the source file and 


the rrrnnorrrv work file. FD suoonm 3everal commands that transfer lmes of text - 
-.-.....r... ~, -~ 
~- 
= = - ~ 
~ 
~~ 
- - ~ 


betwen the source file, the memory buffer, and the temporary, and eventually final, 
file. me followtng table hsts the three basic t a t transfer commands that allow yeu 
to casaly enter the editor, write tu+ to the temporary file, and exit the emtor. 
- 
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Table 6-1. T m Transfer Commands 


Command 
1 
Result 


nA 
Append the next n unprocesacd source lines from the source file 
to the end of the memory buffer. 


1 


Wnte the first n lines of the memory buffer to the temporary 
file ire space. 


E 
End the eda. Copy all buffered text to the temporary file, and 
copy all unprocessed source lines to the temporary file. Rename 
files. 


6.3.1 Appending Tort into the Buffer 


When you start ED and the memory buffer a empty, you can use the A (append) 


command to add text to the memory buffer. 


Note: ED can number lines of t a r to help you keep track of data in the memory 
buffer. me colon that appears when you start ED indicates that hne number~ng is 
~ m e d 
on. Type -V afrer the ED prompt to Nm the line number display off. Llne 


numbers appear on the screen but never become a pan of the output file. 


Rlhe V (Vcnfy Line Numbers) Command 


The V command turns the line number display in front of each line of text on or 
off. The V command also displays the free bytes and total size of the memory bufhr. 
The V command takes the following forms: 
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Initially, the line number display is on. Use -V to Nm it off. If the memory buffer 
a cmpry, or if the current line is at the end of the memory buffer, ED represents the 
line number as five blanks. The OV command prints the memory buffer statistics in 
the form: 


where free is the number of free bytes in the memory buffer, and total e the size of 
the memory buffer. For example, sf you have a total of 48,253 bytes ~n the memory 
buffer and 46,652 of them are free, the OV command displays this information as 
follows 


If the buffer 1s full, the first field, which indicates kee space, is blank. 


The A (Append) Command 


The A mmmand appends, copses, lines from an existing source file into the mem- 
ory buffer. The A command takes the following form: 


where n is the number of unprocessed sourcc lines to append into the memory buffer. 
If a pound sign, #, is given in place of n, then the integer 65,535 is assumed. Because 
the memory buffer can contain most reasonably sized source files, it is often possible 
to issue the command #A at the beginning of the edit to read the entire source file 
into memory. 


When n is 0, ED appends the unprocessed source lines into the memory buffer 
until the buffer is approximately half full. If you do not specify n, ED appends one 
line kom the source file into the memory buffer. 
- 


6.3.2 ED Exit 


You can use the W (Write) command and the E (Exst) command to save your - 


editing changes. The W command wrltes liner from the memory buffer to the new 
file wtthout endlng the ED session. An E command saves rhe contenrs of the buffer 
and any unprocessed material from the source file and exits ED. 
- 


The W (Wnte) Command 


The W command writes lines from the buffer to the new file. The W command 
takes the form: 


where n IS the numhcr of ltner to be wnncn from the hrpnntnp ot the buffer la the 
end of rhc nrw file. If n 1s srearrr than 0. ED wracr n Itncv from the br~~nnnny. 
of 


the buffcr to the cnd of rhc new tile. If n 1s 0. ED wrtrr. lmcr unrtl the bumr nr half 
empty. Thc OW command s a cunvenlcnt way uf makmng room ~n thc mrmorv bullrr 
fur marc Ihnc. from the source file. I f rhc buffer 15 hll, you ;an u ~ c 
~ h c 
OU command 
to wrnrc half rhc contents of the memory buffcr to the new file. You can urc the #U' 
command to write the entire contents of the buffer to the new file. Then you can use 
the OA command to read in more lines from the source file. 


Note: aker a W command is executed, you must cnter the H command to reedit 
the saved lines during the current editing session. 


The E (Exit) Command 


An E mmmand performs a normal exit from ED. The E command takes the form: 


followed by a carriage mum. 


When you cnter an E command, ED first writes all data lines from the buffer and 
the original source file to the $$$ file. If a BAK file exists, ED ddetes it, then renames 
the original file with the BAK filetype. Finally, ED renames the $116 file from file- 
name.$$$ to the original filetype and returns control to the operating system. 


The operation of the E command makes a unwise to edit a back-up file. When you 


edlt a BAK file and exit with an E command, ED eraser your orlgnal file because ~t 
has a BAK filetme. To avoid this, always rename a back-up file to some other filetypc 
before editing ;with 
ED 


Note: any command that terminates an ED session must be the only command on 
the line. 
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6.4 Basic Editing Commands 
- 


The text transfer commands discussed previously allow you to easily enter and exit 
the editor. This section discusses the basic commands that edit a file. 
- 


ED treats a file as a long cham of characters grouped together in lines. ED displays 
and edits characten and lrnes in relation to an imaginary device called the character 
pointer (CP). During an edit session, you must mentally picture the CP's location in - 
the memory buffer and issue commands to move the CP and edit the file. 


The following commands move the character pointer or display text in the vicinity 


of the CP. These ED commands mnsist of a numeric areument and a slnele com- - 


mand lrnrr and muvr be followcd hy a carnage return lhr numcnc arfiurnmr, n, 
dctcrmlnri the number of rmer F.D cxccurc. a command; however, rhcre are four 
,pc~tsl cares to conr~dcr ~n regard to the numrrlc arymcnr: 
- 


m If the numeric argument is omitted, ED assumes an argument of 1. 


1 Use a negative number ~f the command is to be executed backwards through - 


the memory buffer. The B command is an exception. 


1 If you enter a pound sign, X, in place of a number, ED uses the value 65,535 
as the argument. A pound sign argument can be preceded by a minus slgn to - 
cause the command to execute backwards through the memory buffer, -#. 


I ED accepts 0 as a numeric argument only in certain commands. In some 


cases, 0 causes the command to be executed approximately half the possible - 
number of tlmes, while in other cases it prevents the movement of the CP. 


O DIGITAL RESEARCH'" 


6-8 
- 


The following table alphabetically summarms the baric editing commands and 
their valid arguments. 


Table 6-2. Basic Editin= Commands 


Commnd 
I 
Action 


B, -B 
Move CP m the beginning (B) or end (-B) of the memory 
buffer. 


Movc CP n characters forward (nC) or backward (-nC) 
through the memory buffer. 


nD, -nD 
Delete n characters before (-nD) or afrcr (nD) 
the CP. 


I 
Enter inscn mode. 


lstring CTRL-Z 
lnscn a string of characters. 


nK, -nK 
Delete (kill) n lines before the CP (-nK) or after the CP 
(nK). 


DL, -nL 
Move the CP n lines forward (nL) or backward (-nL) 
through the memory buffer. 


nT, -nT 
Type n lines before the CP (-nT) 
or after rhe CP (nn. 


n, -n 
Move the CP n lines before the CP (-n) or after the CP (n) 
and disolav the datination hne. 


- 


The following sections discuss ED'S baric editing commands m more derail. The 
examples m these sectsons illustrate how the commands affect the position of the 
- 
character pointer in the memory buffer. Later examples m Section 6.5, "Combinmg 
ED Commands," illustrate how the commands appear at the screen. For these sec- 
tsons, however, the symbol ^ ~n command examples represents the character pointer, 
which you must imagine in the memory buffer. 
- 


6.4 Basic Editing Commands 
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This section describes commands that move the character polntcr in useful mcre- 


ments hut do not drsplay the dcstlnation line. Although ED is used primarily to 
create and edit program source files, the following sections present a simple text as 
an example to make ED easter to learn and understand. 


The B (BeginningiBomm) Command 


The B command moves the CP to the beginning or bottom of the memory buffer. 
The B command takes the following forms: 


-B moves the CP to the end or bottom of the memory buffer; B mover the CP ro the 
beg~nning of the bufhr. 


'Ihe C (Character) Command 


The C command mover the CP forward or backward the specified number of 
characters. The C command takes the following forms: 


nC, -nC 


when n is the number of characters the CP 1s to be moved. A positive number moves 
the CP towards the end of the line and the bonom of the buffer. A negative number 
moves the CP towards the beginning of the line and the top of the buffer. You can 
enter an n large enough ro move the CP to a different line. However, each ltne IS 
separated from the next by two inv~sible characters: a carriage return and a Imc-feed, 
represented by <cr><lf>. You must compensate for their presence. For example, 11 
the CP is pointlng to the beginning of rhe line, the command 30C moves the CP to 
the next line: 


Emlly Dicklnson raid,<cr><lf> 
"I fin"d ecstasy ~n Ilvin~ -<cr><lf> 


- CP/M 3 User's Guidc 
- The L (Line) Command 


6.4 
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The L command mwcs rhr CP rhc ~pcclficd numhcr of Imncv. After an L ~ommand, 


the CP always po~ntr to the hegnnlng of a lnnr 'Ihr L ~ommand rake, rhc h,llou.~ng 
- forms: 
- 


where n is the number of lines the CP is to be moved. A positive number moves the 
CP towards the end of the buffer. A ncgartve number moves the CP back toward the 
- beginning of the buffer. The command ZL mover the CP two lines forward through 
the memory buffer and posltlons the character pointer at the beglnntng of the line. 


"I f~nd ecstasy ~n living -<cr><lf> 
- 
the mere sense of living<cr><lf> 
^is joy enough."<cr><lf> 
- 
We command -L moves the CP to the beginning of the previous line, even if the 
CP ortg~nally points to a character in the middle of the line. Use the special character 
0 to move the CP to the beginning of the current line. 


The n (Number) Command 


The n command moves the CP and displays the destination line. The n command 
takes the following forms: 


where n is the number of liner the CP 1s to be moved. In response to t h ~ s command, 
ED moves the CP forward or backward the number of lines specified, then pr~nts 
only the destination line. For example, the mmmand -2 mover the CP back two 
lines. 


Emily Dicktnson raid,<cr><lf> 
^"I find ecrtary in living -<cr><lf> 
rhe mere sense of Iwing<cr><lf> 
is joy cnough."<cr><lf> 
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A tunhcr abbrevlarlon of rhlr command s ru cnrcr nu numhcr at all In rrrponw 


to a crrrlapc return wahour a prcccdtnp command, ED arrumrr a n ~ommand of 1 
and moves rhc ( P down to the next llnc and pnnrs ~ r , a. follows 


Emily Dickinron raid,<cr><lf> 
"I find ecstasy ~n llvlng -<cr><lf> 
.the mere sense of living<cr><lf> 


Also, a minus sign, -, without a number moves the CP back one line. 


6.4.2 
Diglaying Memory Buffer Contents 


ED does not display the contents of the memory buffer until you specify which 
part of the text you want to we. The T command displays text without movlng the 
CP. 


The T (Typd Command 


The T command types a specified number of lines from the CP at the screen. The 
T command takes the forms 


where n specifier the number of lines to be displayed. If a negative number is entered, 
ED displays n ltnes before the CP. A positive number displays n hnes after the CP. If 
no number is specified, ED types from the character pointer to the end of the line. 
The CP remains in its original position no matter how many hnes are typed. For 
example, if the character pointer a at the beginning of the memory buffer, and you 
Instruct ED to type four llncs (4T), four liner arc displayed at the screen, but the CP 
stays at the beginning of line 1. 


.Emily Dickinson raid,<cr><lf> 
"I find ccrtary in hying -<cr><lf> 
the mcrc scnsc of living<cr><lf> 
is ioy enough."<cr><lf> 


If the CP 1s between two characters in the middle of the line, a T command wrth 


no number specified types only the characters bcnveen the CP and the end of the 
hne. hut the character nointer stays ~n the same nosition. as shown in the followmr! - 
memory buffer example: 


" I f i n d e c A s t a r r i n l i v i n g - 
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- 
Whenever ED is displaying text with the T command, you can enter a CTRL-S to 
stop the display, then press any key when you are ready to mntinue scrolling. Enter 
a CTRL-C to abon long type-oun. 


6.4.3 
Deleting Chvaeter~ 


The D (Delete) Command 


The D command deletes a spec~fied number of characters and takes the forms: 


nD, -nD 


where n is the number of characters to be deleted. If no number is speufied, ED 
deletes the character to the rlghr of the CP. A positive number deletes multlplc 
characters to the right of the CP, towards the bottom of the file. A negative number 
deletes characters to the lck of the CP, towards the top of the file. If the character 
pointer is positioned in the memory buffer as follows 


Emily Dickinson sald,<cr><lf> 
"I flnd ecstasy in living -<cr><lf> 
the mere rcnre of livlng<cr><lf> 
is loy "enough."<cr><lf> 


the command 6D deletes the SIX characters aker the CP, and the resulting memory 
buffer looks like this: 


Emdy Dickinron raid,<cr><lf> 
"I find ecsrasy in living -<cr><lf> 
the mere renre of I~ving<a><lf> 
is joy .."<a><lf> 
- 
You can also use a D command to delete the <cr><lf> between two lines ro join 
them together. Remember that the ccr> and <If> are two characters. 
- 
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The K (Kill) Command 


The K command kills or deletes whole lines from the memory buffer and takes the 
forms: 
- 


nK, -nK 


where n is the number of liner to be deleted. A positive number kllls lmes after the - 
CP. A negatwe number kills liner before the CP. When no number is specified, ED 
kallr the current line. If the character pointer is at the beginning of the second Ime, 


Emily Dickinron raid,<cr><lf> 
"'I find cntasy in living -<cr><lf> 
the mere renre of living<cr><lf> 
tr joy cnough."<cr><lf> 


then the command -K deletes the previous line and the memory buffer changes: 


^"I find ecstasy ~n living -<cr><lf> 
rhe mere scnre of living<cr><lf> 


IS joy cnough."<cr><lf> 


If the CP is in the msddle of a Ime. a K command kills only the characters from 


the CP to the cnd of thc . ~ n c and concatenates the characters before the (:P wlrh the 
next Ilnc. A -K command dclctcr all the chara.rcrr 
hrrwen the hcgtnn~ng of the 


prcvlour llnc and the CP. A OK command dcletc. rhc charactcrv on the lhnc up to rhc 
CI' 


You can use the specla1 # character to delete all the t e n from the CP to the 


begnnnng or end of the buffer. Be careful when using #K because you cannot reclaim 
lmer aker they arc removed from the memory bufhr. 


6.4.4 
Inserting Characters into the Memory Buffer 


The I (Insert) Command 


To insert characters into the memow bufhr from the screen, use the I command. 
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- If you enter the command in uppcr-case, ED automat~cally converts the strlng to 
upper-case. 'lhe I command takes the forms: 


When you type the first command, ED cnten inwn mode. In this mode, all key- 
strokes are added directly to the memory buffer. ED mterr charactem in lines and 
does not star a new line until you press the enter key. 


NEW F I L E 
: x i 


1 : 
E m i l y D ~ c X i n s o n s a l d t 


2: 
"1 f i n d e e r t a s r i n l l v i n l - 


3: 
t h e mere s e n r e o f l i u i n # 


4: 
i 5 J O Y e n o u g h . " 


5 : 
^ Z 


: 


Note: to exlt from insert mode, you must prcss CTRL-Z or ESC. When the ED 
prompt, ', appears on the screen, ED is not in insert mode. 


In command mode, you can use CP/M 3 command line-editing control characters. 
In insert mode, you can use the control characters listed in Table 6-3. 


Table 6-3. CP/M 3 Line-editing Controls 


Command 
Result 


CTRL-H 
Delete rhe last character typed on the current line. 


CTRL-U 
Delete the entire line currently being typed. 


Delete the entire line currently being typed. Same as CTRL-U. 


Backs~ace 
Remove the last character. 


When entering a combination of numbers and letters, you might find it inconve- 
nient to press a caps-lock key d your term~nal translates the upper-case of numbers 
to special characters. ED provides two ways to translate your alphabetic input to 
uppcr-case without affecting numbers. The first is to enter the znrert command letter 
in upper-case: I. All alphabetlcs entered during the course of the capitalized com- 
mand, either in insert mode or as a string, are translated to uppcr-case. If you enter 
the tnsert command letter in lower-case, all alphabetics are inserted as typed. The 
second method IS to enter a U command before inserting ten. Upper-case translation 
rematns in effect unt~l you enter a -U command. 


The 1srnng"Z (Insert String) Command 


The second form of the I command does not enter insert mode. It inserts the 
character string into the memory buffer and returns lmmedlately to the ED prompt. 
You can use CP/M 3's line-editing control characters to edit rhe command string. 


To inscn a srnng, first use one of the commands that posttion the CP. You must 
move the CP to the place where you want to inscn a stnng. For example, if you 
wanr to insert a string at the beginning of the first line, use a B command to move 
the CP to the beginn~ng of the buffer. With the CP positioned correctly, enter an 
insert string, as follows 


This inserts the phrase "In 1870," at the bcgnning of the first Ime, and returns 


immediately to the ED prompt. In the memory buffer, the CP appears afrer the 
inserted srnng, as follows 


In 1870,'Emily Dicktnson said,<cr><lf> 


6.4.5 
Replacing Characters 


The S (Substitute) Command 


The S command searches the memory buffer for the specified string, but when 11 


finds a, automatically subsurutes a new string for the search string. Whenever you 
enter a command in upper-case, ED automatncally converts the strtng to upper-case. 
The S command takes the form: 


nSsearch srringeZnew string 
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where n is the number of substltut~ons to make. If no number is spec~fied, ED 
searches for the next occurrence of the search strlng in the memory buffer. For 
example, the command 


sEnilr D ~ c l i n s o n ~ Z T h r 
p o e t 


searches for the first occurrence of "Emily Dickinson" and substitutes "The poet." In 
the memory buffer, the CP appears after the substltutcd phrase, as follows 


If upper-case translation is enabled by a capital S command letter, ED looks for a 
capitalized search strlng and insens a capitalized insen string. Note that d you com- 
bine this command with other commands, you must termmate the new string with a 
rnL-z. 


6.5 Combining ED Commands 


It saves keystrokes and edrting rime to combme the editing and display commands. 
You can type any number of ED commands on the same line. ED executes the 
command string only after you press the carriage return key. Use CP/M 3's linc- 
editing controls to manipulate ED command strings. 


When you combine several commands on a line, ED executes them in the same 
order they are entered, from left to right on the command line. Them are four 
restrictions to combining ED commands: 


1 The mmbincd-mmmand line must not exceed CPlM 3's 128 character 
maximum. 


m If the combined-command line contains a character string, the line must not 
exceed 100 characters. 
Commands to terminate an editing session must not appear m a combined- 
command line. 
Commands, such as the I, J, R, S, and X commands, that require character 
strings or filespecs must be either the last command on a hne or must be 
terminated wlth a CTRL-Z or ESC character, even if no character strtng or 
filespec ts given. 
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While the examples in the previous sectlon show the memory buffer and the posi- 
tion of the character pointer, the examples in this section show how the screen looks 
during an editing session. Remember that the character pointer is imaginary, but you 
must picture i s location because ED'S mmmands dlrplay and edit text in relation ro 
the character pointer. 


6.5.1 Moving the Character Pointer 


To move the CP to the end of a line without cal~lating the number of characters, 
combine an L command with a C command, L-2C. This command strlng accounts 
for the <cr><lf> sequence at the end of the line. 


Change the C command in this command string to move the CP more characters 
to the left You can use this command string lf you must make a change at the end 
of the hne and you do not want to calculate the number of characters before the 
change, as in the following example 


6.5.2 
Displaying Text 


A T command types from the CP to the end of the line. To see the entlre line, you 
can combine an L command and a T command. Type Olt to move the CP from the 
middle to the beginnq of the line and then display the entlre line. In the following 
example, the CP is in the mlddle of the Ime. OL moves the CP to the beginnxng of 
the Ime. T types from the CP to the end of the line, allowing you to see the entire 
bne. 


sense o f l i u i n s 


3: * O L T 
3: 
t h e m e r e s e n s e o f l i u l n d 


3: 


The command 0TI displays the entire line without moving the CP. 
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To verify that an ED command moves the CP correctly, combine the command 
- with the T command to display the line. The following example comblncs a C 
command and a T command. 


4: r B x T 
1 : 
E r i l v D ~ c K i n s o n s a i d . 
- 
2: 
" I f i n d e c s t a r u ~n l ~ u i n l - 


3 : 
t h e mere s e n s e o f l i v i n g 


4: 
i s J o r enough." 
- 
1: ' 


6.5.3 Editing 
- 
To edlt t e n and verify corrections quickly, combine the edlt commands with other 
ED commands that move the CP and display text. Command strings like the one 
that follows move the CP, delete specified characters, and venfy changes quickly. 


Combrne the edit command K with other ED commands to delete entlre lines and 
verify the correction quickly, as follows 


1 : +ZLZKBXT 
1 : 
E l l l l D i o K l n ~ o n s a i d , 


2: 
" I f i n d r c s t a s v i n l i u l n l - 


1 : * 


The abbreviated form of the I (insen) command makes simple tumal changes. To 


make and verify these changes, combme the I command string with the C command 
and the OLT command string as follows. Remember that the Insen strlng must be 
terminated by a CTRL-Z. 


1 : r 2 O C i t o a f r i e n d e Z O L T 
1: 
E m i l y O i c K i n s o n s a i d t o a f r i e n d * 


1 : I 
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6.6 Advanced ED Commands 
- 


The basic edttlng commands discussed previously allow you to use ED for all your 


edlting. The following ED commands, however, enhance ED's usefulness. 
- 


6.6.1 Movitlg the CP and Displaying Text 


The P (Page) Command 
- 


Although you can display any amount of text at the screen with a T command, it 
is somnlmes more convenient to page through the buffer, vicwlng whole screens of 
data and moving the CP to the top of each new screen at the same time. To do ths, - 


use ED's P command. The P command takes the following forms: 


where n is the number of pager to be displayed. If you do not specify n, ED rypes 
the 23 lina following the CP and then moves the CP forward 23 liner. This leaves - 
the CP polnttng to the fint character on the screen. 


To display the current page without moving the CP, enter OP. The special character 


0 prevents the movement of the CP. If you specify a negative numbcr for n, P pages - 
backwards towards the top of the file. 


The n: (tine Number) Command 
- 


W e n line numbers are bcxng daplayed, ED accepts a linc number ar a command 
to specify a dcstnnation for the CP. The line number command takes the follow~ng 
form: 
- 
- 


where n is the numbcr of the destination linc. This command places the CP at the 
beginning of the specified line. For example, the command 4: mova the CP to the 
begnning of the fourth line. 
- 


Remember that ED dynamically renumbers ten lines in the buffer each time a linc 
is added or deleted. Therefore, the number of the destination linc you have in mind 
can change during editmg. 
- 


The :n (Through Ltne Number) Command 


The Inverse of the line number command specifics that a command should be 


executed through a certatn line number. You can use rhis command w,th only three 
ED commands: the K (kill) command, the L (line) command, and the T (type) com- 
mand. The :n command takes the following form: 


where n is the line number through which the mmmand is to be executed. The :n 
part of the command does not move the CP, but the command that follows it mlghr. 


You can combine n: with :n to spcufy a range of liner through which a command 
should be executed. For example, the command 2::4T types the second, third, and 
fourth lines: 


1: tz::ar 
2: 
" I f i n d e c s t a s y i n l i v i n g - 


3: 
t h e mere sense o ? l i v i n g 


4: 
i s J a v e n o u r h . " 


2: t 


6.6.2 Finding and Replacing Character Strings 


ED ruppom a find command, F, that searches through the memory buffer and 
place the CP after the word or phrase you want. The N command allows ED to 
search through the entlre source file instead of just the buffer. T h e ] command 
searches for and then juxtaposes character strings. 


The F (Find) Command 


The F command performs the s~mplest find function; it takes the form: 


where n is the occurrence of the string to be found. Any number you enter must be 
positwe because ED can only search from the CP to the bottom of the buffer. If you 
enter no number, ED finds the n a t occumnce of the string in the file. In the follow- 
m g example, the second occurmnce of the word Living is found. 
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The character pointer moves to the beginning of the thnrd line where the second 
occurrence of the word "living" is located. To display the line, combine the find 
mmmand with a rype command. Note that if you follow an F command wth another 
ED command on the same line, you must terminate the strlng with a CTRL-Z, 
as 
follows 


It makes a difference whether you enter the F command in upper- or lower-case. If 
you enter F, ED internally translates the argument smng to upper-caa. If you rpeclfy 
f, ED looks for an uaa match. For example. Fcptm 3 searches for CP/M 3 but 
fcplm 3 searches for cp/m 3, and cannot tind CP/M 3. 


If ED does not find a match for the string in the memory buffer, it issues the 


message, 


BREAK " x " A 1 


where the symbol # indicates that the search failed durlng the execution of an F 
command. 


The N Command 


The N command extends the search function beyond the memory buffer to include 
the source tile. If the search 1s successful, it leaves rhc CP pointing to the fint char- 
acter aker the search string. The N command takes the form: 


where n is the occurrence of the string to be found. If no number is entered, ED 
looks for the " e n occurrence of the strtng in the tile. The case of the N command 
has the same effect on an N command as it does on an F command. Note that ~f you 
follow an N command w~th another ED command, you must terminate the string 
w~th a CTRL-Z. 


When an N command is executed, ED searches the memory buffer for the spedficd 


string, but if ED does not find the string, it does not issue an error message. Ingtead, 
ED automatically wrlns the searched data from the buffer into the near file. Then 
ED performs a OA command to fill the buffer with unsearchcd data from the source 
filc. ED continuer to search the buffer, write out data, and append new data until it 
either finds the string or reaches the end of the source file. If ED reaches the end of 
the source filc, ED lssucs the following message: 


BREAK "*" AT 


Because ED writes the searched data to the new file before looking for more data 


m the source file, ED usually wntes the contents of the buffer to the new file before 
finding the end of the source file and rssulng the error message. 


Note: 
you must USF the H command to continue an edit sesri&i after the source file 


IS exhausted and the memory buffer is emptied. 


The J uuxtapore) Command 


The J command xnserts a string after the search string, then deletes any characters 


bmveen the end of the inserted strlng to the beginning of the a third deleteto string. 
This juxtaposes the string between the rearch and delete-to strings with the insert 
strmg. The J command rakes the form: 


nJsearch stringeZinscrt rtring"Zdclme.to string 


where n is the occurrence of the search string. If no number is specified, ED searches 
for the next occurrence of the search str~ng m the memory buffer. In the following 
example, ED searches for the word "Dibinson", inserts the phrase "told a friend" 
after it, and then deletes everything up to the comma. 


1: + r T 
1: 
E a l l r D i c k i n s o n s a i d * 


2 : 
'"I f i n d e c s t a s y I" 
l i v i n g - 


3: 
t h e m e r e o f l l u l n r 


4: 
i s 4 0 7 enough," 


1: + ~ O i c X i n s o n " Z t o l d a f r i e n d A Z , 
1 : * O l t 
1 : 
E m i l y D i c k ~ n s o n t o l d a f r i e n d . 
1: 
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If you combine this command with other commands, you must terminate the 
delete-to str~ng with a CTRL-Z or ESC, as in the following example. If an upper- - 


case I command letter is specified, ED looks for uppcr-case search and dclere-to 
strings and Inserts an upper-case insert string. 


The ] command is especially useful when revising comments in assembly language - 


source code, as follows 


236: 
SORT 
L X I 
H, SW 
;ADDRESS TOGGLE SUITCH 
- 


236: * J I "ZADDRESS SWITCH TOCCLEAZ'L ^ZOLT 
236: 
SORT 
L X I 
HI SW 
;ADDRESS SUITCH TOGGLE 
236: r 
- 


In this example, ED search- for the first semicolon and in& 
ADDRESS SWlTCH 


TOGGLE alter the mirk and then delcnr to the <cr><lf> sequence, represented by 
ClRL-L. In any search string, you can use CTRL-L to represent a <cr><lf> when - 


the phrase that you want extends across a hne break. You can also use a CI?(L-I in 
a search srnng to represent a tab. 
- 


Note: 
if long strings make your command longer than your screen line length, enter 


a CTRL-E to cause a physical carnage return at the screen. A ClRL-E returns the 
cursor to the left edge of the screen, but does not send the command line to ED. - 
Remember that no ED command line containing strings can exceed 100 characters. 
W e n you finish your command, press the carriage return key to send the command 
to ED. 
- 


The M (Macro) Command 


An FD macro command, M, can lnrrcaw the urcfulnrrs of a n n n ~ 
of commands. - 


'lhc M command allows you to group ED commands tupcther for rcprarcd rxccu- 
ston. The hl command rakcs the f<,lloumg form 


nMcommand string 
- 


where n is the number of times the command string is to be executed. A negative 
number 1s not a valid argument for an M command. If no number a spcclfied, the - 
specla1 character X 1s assumed, and ED executes the command string until it reaches 
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the cnd of data in the buffer or the end of the source file, depending on the com- 
mands specified in the string. In the following example, ED executes the four com- 
mands repetruvely until it reaches the end of the memory buffer: 


1: *rlllvin#'Z-6diLivinIaZOlt 
2: 
"I f i n d e c s t a s y I" L i u x n r - 


3: 
t h e m e r e s e n s e o f L i v i n r 


BREAK "*" AT ^Z 


3: 


The terminator for an M command IS a carnage return, therefore, an M command 


mu,r bc rhr Inst command on rhr I~nc. Alvo, all chrrastcr ,trmp that appear ~n a 
macro must bc tcrmtnarrd by CTRI.-7 or ESC. If a character rrring end, rhc con- 
bmcd.cummand anng, 11 must bc rcrmlnarrd by CTRI -7.. then folluwcd hv a <crz 
to end the M command. 


The e x a t i o n of a macro command always ends in a BREAK"*" message, even 
when you have limited the number of times the macro is to be performed, and ED 
does not reach the end of the buffer or source file. Usually the command letter 
d!~playcd m the message is one of the mmmands from the string and not M. 


To abort a macro command, press a CTRL-C at the keyboard. 


The Z (Sleep) Command 


Use the Z command to make the editor pause between operations. The pauws give 
you a chance to review what you have done. The Z command takes h e following 
form: 


where n is the number of seconds to wait before proceeding to Ihc next instruction. 


- 
Usually, the Z command has no real effect unless you uw it with a macro com- 
mand. The following example shows you how you can use the Z command to cause 
a brief pause each time W finds the word TEXT in a file. 


6.6 Advanced ED Commands 


6.6.3 
Moving Ten Blocks 


To move a group of lines from one area of your data to another, use an X 
command to write the t a t block into a temporary LIB file, then a K command to 
remove these lines from their oripjnal location, and finally an R command to read 
- 


the black into its new location. 


The X (Transfer) Command 


The X command taker the forms: 


where n is the number of lines from the CP towards the bomom of the buffer that 
arc to be transferred to a file. Therefore, n must always be a positive number. The 
nX command with no file specified creates a temporary file named X$$$$$$$.LIB. 
This file ~s erased when you terminate the edit scsnon. The nX command wrth a file 
speclficd creates a file of the specified name. If no filc~ype is specified, LIB is assumed. 
This file is saved when you terminate the e d ~ t session. If the X command rs not the 
last command on the line, the command must be terminated by a CTRL-Z or ESC. 
In the follow~ng example, just one line is transferred to the temporary file: 


1: * X 
1 : * t 
1: * E m i l y D ~ c L i n s o n s a i d , 
1 : * k c 
1 : * " I f i n d e c s t a s y i n l i v i n g - 
1 : 


If no library file is specified, ED looks for a file named XS$$$$I$.LIB. If the file 


doer not cxlsr, ED creates it. If a previous X command already created the library 
file, ED appends the specified hnes to the end of the existing file. 


Use the specla1 character 0 as the n argument in an X command to delete any file 


fmm wlthin ED. 


- 
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- 
The R (Read) Command 


The X command transfers the ncn n lines from the current line to a library file. 
- 


The R mmmand can retrieve the transferred Imes. The R command taker the forms: 


- 


If no filename is specified, X$$$$$$$ is assumed. If no filetype is specified, LIB is 


assumed. R inserts the library file in front of the CP; therefore, alter the file is added 
- 
to the memory buffer, the CP points to the same character it did before the read, 
although the character is on a new line number. If you combine an R command wrth 
other commands, you must separate the filename from subsequent command lmers 
with a CTRL-Z as in the following example where ED types the entire file to vcrlfy 
- 
the mad. 


1: +41 
- 
: r R " Z 6 x T 


1: 
" I l t n d e c s t a s r in l i v i n g - 
2: t h e m e r e s e n s e o f l i v i n g 
- 
3: 
1 s j o y e n o u g h . " 


4: 
E n i l r D i c K i n s o n s a i d t 


1: I 
- 
6.6.4 
Saving or Abandoning Chmges: ED Exit 


You can save or abandon cdring changes wlth the follow~ng three commands. 
- 
The H (Head of File) Command 


An H command $auc$ the mntcntr of the memory buffer w~rhour endlng rhr ED 
- 
?c~v~on, 
hut tt returns to the head of rhc file It rwcr the zuncnt changes and Ins you 


reed,, the file w~rhout cxlttng ED Thc H command rako the following form: 


H 
- 


followed by a carnage return. 


- 
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To execute an H command, ED fist finalizes the new filc, transferring all lines 
remaining in the buffer and the source file to the new file. Then ED closes the new - 


file, cram any BAK file that has the same file spedficadon ar the original source file, 
and rmames the original source file filename.BAK. ED then renames the new file, 
whtch has had the filetype $S$, with the orlgtnal file spccrfication. Finally, ED opens - 
the newly renamed file as the new source filc for a new edit, and opens a new S$S 
file. When ED mums the ' prompt, the CP is at the beginning of an empty memory 
buffer. 
- 


If you want to send the edited material to a file other than rhe original file, use the 
following command: 


If you then rcstan the edtt with the H command, ED renames the file differentfile- - 


name.$$$ to d~fferentKlename.BAK and creates a new filc of difbrmtfilespcc when 
you finish editing. 


We 0 (Original) Command 
- 


An 0 
command abandons changes made since the bepning of the edit and allows 
you to return to the original source file and begin reediting wtthout ending the ED - 
session. The 0 command raker the form: 


followed by a carriage r a m . When you enter an 0 mmmand, ED confirms that 
you want to abandon your changes by ask~ng 
- 


You must respond with either a Y or an N; if you press any other key, ED repeats - 


the question. When you enter Y, ED erases the temporary file and the contents of the 
memory buffer. When the 
prompt returns, the character polnter is pointing to the 


bcginn~ng of an empty memory buffer, just as it is when you stan ED. 
- 


The Q (Quit) Command 


A Q command abandons changes made sine the beg~nning of the ED sesston and 
exits ED. The Q command taker the form: 


followed by a carriage return 


When you enter a Q command, ED verifies that you want to abandon the changes 
by asking 


You must respond with either a Y or an N; ~f you press any other key, ED repeats 
the question. When you enter Y, ED erases the temporary file, doses the source file, 
and returns control to CP/M 3. 


Note: you can enter a CTRL-Break or a CTRL-C to return control immcdiatcly to 
CP/M 3. This does not give ED a chance to close the Source or new files, but it 
prevents ED from deleting any temporary files. 


6.7 ED Error Messages 


ED returns one of two types of error messages: an ED error message ~f ED cannot 
execute an edit command, or e CP/M 3 error message if ED cannot read or write to 
the specified fik. An ED error message taker the farm: 


BREAK "x" AT c 


where x is one of the symbols defined in the following table and c is the command 
lmer where the error occurred. 
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Symbol 


# 


Table 6-4. ED Ermr Symbols 


1 
Meonmg 


Search failure. ED cannot find the string specified in a F, S, or N 
command. 


Unrecognized command letter c. ED does not recognize the indl- 
cared command letter, or an E, H, 0, 
or Q command a not alone 
on its command line. 


No. LIB file. ED did not h d the LIB file speafied in an R command. 


Buffer full. ED cannot put anymore characters in the memory buffer, 
or string specified in an F, N, or S command is roo long. 


Command aborted. A keystroke at the keyboard aborted com- 
mand execution. 


F~le error. Followed bv either disk FULL or DIRECTORY FULL. / 


- 


The following examples show how to recover from common edlttng error condi- 
tions. For example 


BREAK " > " 
AT A 
- 


means that ED filled the memory buffer before completing the execution of an A 
command. When rhsr occurs, the character pointer is at the end of the buffer and no - 
edmting is possible. Use the OW command to write out half the buffer or use an 0 or 
H command and reedit the file. 
- 


BREAK "r" A T F 


means that ED reached the end of the memory buffer without marching the string in 
an F command. At this point, rhe character pointer s at the end of the buffer. Move - 


the CP wcth a B or n: line number command to resume cdtting. 


BREAK "Fa' AT F 
D I S K FULL 


Use the OX mmmand m maw an unnmssary file on the disk or a B+Xd:buMr.sav 


command to write the contents of the memory buffer onto another disk. 


BREAK " F " AT n 
DIRECTORY FULL 


Use the same commands described in the previous message to recover from this file 


error. 


The following table defines the dirk file error messages ED returns when a cannot 
read or wr~te a file. 


Table 6-5. ED Diskette File Error Messages 


Message 
Meantng 


CP/M E ~ P O P 
on d : 
R e a d l O n l v F l l r 


BOOS F u n c t ~ o n = NN 
F i l e = FILENAME.TYP 


Disk d: has Read-Only attribute. This occurs if a different disk 
has been inserted in the drive sina the last cold or warm boat. 


* * F I L E I S R E A D O N L Y I I 


The file spectfied in the command to invoke ED has the RiO 
attribute. ED can read the file so that the user can examine it, 
but ED cannot change a Read-Only file. 


End of Section 6 
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Appendix A 
CP/M 3 Messages 


Messages come from several different sources. CPlM 3 can display error messages 
when the Basic Disk Operaring System (BDOS) returns an error code. CPlM 3 can 
also display messages when them arc crmrs in command liner. Each utility supplted 
with CP/M 3 has its own set of messages. The following table lists CP/M 3 messages 
and utility messages. If you am runntng an application program, you might see 
messages other than those lisnd here. Check the application program's documenta- 
tion for explanations of those messages. 


Ihe messages in Table A-l might bc preccdcd by ERROR:. Some of them might 


also be pmeded or followcd by the filespec of the file causing the error condition. 
Sometimes the input hne is flagged with an up arrow t , to indicate the character 
that caused the error. In this case, the message, E r r o r a t t h e ^, precedes the 
appropriate error message. Some of the messages are followed by an additional line 
preceded by INPUT:, OFTON:, or DRIVE: followed by the applicable enor message. 


Table A-1. CP/M 3 Merrana 


Messaxe 
Meaning 


A s s i g n a ~ a s s ~ o r d t o t h i ~ 
f i l e * 


SET. A puswad mode has been s e l d fer this file but no 
password has been assigned. 


AuxiliaPY d e v i c e r e d i r e c t i o n n o t imPlemrntcd. 


GET and PUT. AUXIN and AUXOUT cannot bc redirected to 
a file. 


Bad c h a r a c t e r , r e - e n t e r 


GENCPM. The character entered war not a number. 
1 


Table A-1. 
(continued) 


Message 
Meaning 


Bad c l o s e . 


SAVE. An error occurred durinp the attempt to close the file, 
probably because the file is write-protected. 


( B a d L o r i e a l D e u l c e A s s i I n m e n t i 
I 
DEVICE. Only the fouowing logical devices are valid: CONIN:, 
CONOW:. AUXIN:. AUXOW:. LST:. 


1 BLD PLRAMETER 
I 


PIP. You entered an illegal parameter in a PIP command. Retyrx 
the entry correctly. 


Bad p a s s w o r d . 


RENAME. The password supplied by the user a incorrect. 


Bank o n e n o t a l l o w e d . 
I 
GENCPM. Bank 1 cannot be defined as available during sys- 
tem generation. 


Baud r a t e c a n n o t b e s e t f o r t h i r d e v i c e . 


DEVICE. Only physical devices that have the SOFT-BAUD 
attribute can have their baud rates changed. To check the ami- 
butes of the physical device, type DEVICE physical-dw. 
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Table A-1. (continued) 


Message 
Meaning 


B r e a k " x ' a t c 
- 


ED. "r" is one of the symbols described below and c is the 
command letter being executed when the error occurred. 
I 
* 
Search failure. ED cannot find the string specified in an 
F, N, or S mmmand. 


? 
Unrecognized mmmand lencr c. ED does not recognize 
the indicated command lemr, or an E, H, 0 , or Q com- 
mand is not alone on its command line. 


0 
The file specified m an R command cannot be found. 


> 
Buffer full. ED cannot put any more characters in the 
memory buffer, or the string specified in an F, N, or S 
mmmand is too long. 


E 
Command aborted. A keystroke at the console aborted 
command execution. 


F 
Dirk or dnrrctory full Thlr error Is followed by cjrhcr 
the dtrk or dimitory full rncn,apr. Rcfcr to the rccovcv 
proccduro lrrtcd under rhcrc mcrrapr. 


CANNOTCLOSE: 
C a n n o t c l o s e file. 
CANNOTCLOSE F I L E , 
CANNOTCLOSEDESTINATlONFILE - f i l e s p e c 


GENCOM, HEXCOM, UB80m, LINK-80, 
MAC, PIP, RMAC, 


SUBMIT. An output file cannot be closed. This can occur ~f the 
dlsk is removed before the program terminates. 


C a n n o t d e l e t e f i l e . 


I 


GENCOM. CP/M cannot delete a file. Check to see if the COM 
file is Read-Only or password-protected. 


Table A-1. 
(continued) 


Message 
Meaning 


C a n n o t h a v e b o t h c r e a t e and a c c e s s t i m e s t a m p s . 


SET. CP/M 3 supports either create or access time stamps, but 


C a n n o t l a b e l a d r i v e u i t h a f i l e r e f e r e n c e d , 
+-- 


SET. SET docs not allow mixing of files and drives. 


CANNOTOPENSOURCEFILE 


HEXCOM. The HEX file is not on the specified drivels). 


C a n n o t r e d i r e c t f r o m B I O S , 


GET, PUT. This message is d~splaycd as a warning only if the 
system has an invahd BIOS. 


C a n n o t s e t b o t h RO and RW, 


SET. A file cannot be set to both Read-Only and Read-Write. 


C a n n o t 4 c t b o t h SYS and D I R I 


SET. A file cannot be set to both SYS and DIR. 


CAN'TOELETE T E M P F I L E 


PIP. A temporary I$$ file already exists which is Read-only. 
Use the SET command to change the attribute to Read-Write, 
then erase ~t. 


Table A-1. 
(continued) 


Merragc 
Meoning 


CHECKSUMERROR. 
Checksum e r r o r 


HEXCOM, PIP. A hex record checksum error war encoun- 
tered. The hex remrd that produced the error must be cor- 
rected, probably by recreating the hex file. 


C l o s e e r r o r . 


XREF. This message is preceded by the filcname.XRF. The dlsk 
might have been removed before the program terminated. 


C l o s e o ~ r r a t i o n 
f a i l e d . 


COPYSYS. There was a problem in closing the file at the end 
of the file copy operation. 


C l o r l n s f l l e H E L P . D A T 
C l o s i n s f i l e H E L P . H L P 


HEW. HELP enmunerd m o r while processing the HELP.DAT 
or the HELP.HLP file. 


C O M f i l e f o u n d a n d N U L L o ~ t l o n , 


GENCOM. The NULL option imphcs that no COM file b to 
be loaded, just the RS&. 


.CUM f i l e r e s u ~ r e d 


DIR, ERASE, RENAME, TYPE. Options in the built-m com- 
mand line require support from a transient COM file that 
CP/M 3 cannot find on disk. 


I COMMON ERROR: 


LMK-80. An undefined common block has been elected. 
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PIP. A hex record checksum was encountered during the trans- 
fer of a hex file. The hex file with the checksum error should 
be corrected, probably by recreating the hex file. 
1 - 


Table A-1. (continued) 
- 


I CPMLDR e r r o r : f a i l e d t o o p e n CPM3.SYS 
I 


Message 
Meantng 


CORRECTERROR, TYPE R E T U R N O R C T R L - Z 


CPMLDR. The system file CPM3.SYS is missmg. 


CPMLDR e r r o r : f a i l e d t o r e a d CPM3.SYS 


- 


CPMLDR. An error occurred whtle reading CPM3.SYS. 


C P l M E r r o r on d: D i s k I I O 
B O O S F u n c t i o n = x x F l l e = f i l e s p e c 


CP/M displays the preceding merrage if the disk is defective or 
improperly formaned (wrong dcnslty). 


C P l M E r r o r o n d: I n v a l i d D r i v e 
B O O S F u n c t i o n = xw F i l e = f i l e s p e c 


CP/M 3 displays rhe preceding message whcn there is no disk 
in the drive, the drrve latch is open, or the power is off. It also 
displays the message whcn the specified drrvc is not in the 
system. 


C P l M E r r o r o n d : R e a d / O n l v D i s K 


1 B D D B F u n c t ~ o n 
= x x F i l e = f ~ l e s ~ e c 


- 
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CP/M 3 does not allow you to erase, rename, update, or set 
attributes of a file residing in a Read-Only dnve. Use rhe SET 
mmmand m ser the drive attribute to Read-Write. 
- 


- 
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CP/M 3 does not allow you to erase, rename, update, or set 
attributes of a file that is Read-Only. Uw the SET command to 
u t the file attribute to Read-Write. 


Tabls A-1. 
( c d u e d ) 


Date a n d T i m e S t a a ~ i n l I n a c t i v e . 


DIR. The DATE option was specified, but the disk directory 
has not been initiallzed with dateltime stamping. 


- 
- 


PIP. The dcstinatlon file specified ~n a PIP command already 
exists and it is Read-Only. B you type Y, 
the destination file is 


deleted before the file mpy is done. If you type N, PIP displays 
the message .'NOT 
DELETED" 
and aborts the copy 


D e u i e e R e a s s i g n m e n t Not S u ~ ~ o ~ t e d d 
E n t r r n e w a s s i l n r e n t o r h i t RETURN. 


Message 
Meaning 


C P I M E r r o r on d : R e a d l O n l ~ F i l e 
BDOSFunctlon = u x F i l e = f i l e r ~ e e 


I 
DEVICE. A device assignment is invalid. 
I 
- 
- 


D i r r c t o r v a l r e a d y r e - f o r m a t t e d . 


INImIR. The directory already has datelnmc stamping. 


Table A-1. 
(continued) 


Message 
Meantng 


D i r e c t o r y f u l l 
OIRECTORYFULL 


ED. There is not enough directory space for the file being writ- 
ten to the destination disk. You can use the OXhlespec mm- 
mand to erase any unnecessary filer on the disk without leaving 
the editor. 


SUBMIT. There is not enough directory space on the tempo- 
ram filc drive to write the temnorarv filc used for orocessine 
. . 
SUBMIT filer. Urc the SETDEF command to determrnc which 
dnvr fir the temporary file drlvc. Use the ERASF command to 
era- unncrrrrnry 610 or rrr rhc temporary file drtvr to a dll. " I 
fcrent drive and retry. 
LIB-80, LINK-80. There is no directory space for the output ot 
intermediate files. Use the ERASE command to remove unnec. 
essary files. 
GENCPM. There is no directory space for CPM3.SYS. 
HEXCOM. There is no directory space for the output COM 
file. 


I director^ n e e d s t o b e r e f o r m a t t e d f o r d a t e l t i m e stamps. 
I - 


SET. A datehime option was specified, but the directory has 
not b n n initialized for datdtime stamping. Use the INITDIR 
- 


mmmand to ~nitialize the directory for datcltimc stamping. 


1 D I S K FULL 
I - 


ED. There is not enough disk space for the output file. This 
error can occur on the E, H, W, or X commands. If a occurs 
with X command, you can repeat the mmmand prefixing the 
filename with a different drive. 
- 


Table A-1. 
(continued) 


Message 
Meaning 


DISK RERD 
DISK RERDERROR: 
D i s k r e a d e r r o r : f i l e s p e c 
DISK READERROR - f i l e s p e e 


GENCPM, HEXCOM, LIB-80, LMK-80, PIP. The disk file 
specified cannot be mad. 


DISK U R I T E . 
D i s k W r i t e E r r o r 
DISK URITEERROR: 
DISK URITEERROR - f i l e s m 


HEXCOM, LIB-80, LINK-80, PIP, SUBMIT. A disk write 
operation cannot be ~uccessfully performed probably because 
the disk is full. Use the ERASE command to remove unncms- 
sary files. 
- I DO y o u w a n t a n o t h e r f i l e ? ( Y I N ) 
I 
PUT. Enter Y to redirca ourput to an additional file. Othcr- 
wise, enter N. 


I D r i v e d e f i n e d t w i c e i n s e a r c h p a t h 
I 


SETDEF. A drive can be spcdfied only once in the warch path 
order. 
- I o l i v e R e a d 0 n 1 r 
I 


- 


ERASE, RENAME. The specified file is on a Read-Only drive 
and cannot be erased or renamed. 


D r i v e s p e c i f i e d h a s n o t b e e n d e f i n e d . 
- 
GENCPM. 'lhe drive specified has not been ddincd yet. Buffer(s) 
have not bcen allocated for the drive. 


GENCOM. The specified RSX is already anachcd to the COM 
file. The old one is discarded. 
I - 


Tablc A-1. 
(continued) 


GENCOM. Two or more RSXs of the same name are spec~fied. - 
GENCOM uses only one of the RSXs. 


Merroge 
Meaning 


O u ~ l i c a t e R S X i n h e a d e r , R e ~ l a c i n g o l d 
b y new, 


T h ~ s 
f ~ l e w a r n o t u s e d . 


E q u a l s ( ' 1 d e l i m i t e r m i s s ~ n ~ a t 
l i n e N N N 


GENCPM. The equal sign is missing in the specified line. 
1 - 


- 
- 


/ E N D OF FILE + - 2 I ? 
I - 


I 
PIP encountered an unexpected ad-of-file during a HEX file 
transfer. 
I - 


/ End o f l i n e e x p e c t e d . 


DEVICE, GET, PUT, SETDEF. The command typed does not 
have any funher parameters. An end-of-line was expected. Any 
funher characters on the line were ignored. 


E r r o r a t end o f l i n e : 


DEVICE, GET, PUT, SETDEF. The error detected occurred at 
the end of the input lme. 


I Error on l i n e nnnnn: 
I - 
SUBMIT. T h e SUBMIT program displays its messages m the 
preceding format, where nnnnn represents the line number of 
the SUBMIT file. Refer to the message following the line num- 
ber for explanation of the error. 
- 


- 
Tsble A-I. 
(continued) 


F I L E ERROR 


ED. Disk or directory is full, and ED cannot wrlte anythlng 
more on the disk. This is a fatal error, so make sure rhere is 
enough space on the disk to hold a second copy of the file 
before invoklng ED. 


F i l e a l r e a d y e n l s t s i D e l e t e i t 7 ( Y I N I 
f i l e a l r e a d v e x i s t s * d e l e t e ( Y I N I ? 


PUT. Enter Y to delete the file. Otherwise the program 
terminates. 
RENAME. The above message is preceded by filespec. You 
have asked CP/M 3 to create or rename a file using a file 
spedfication that is already assrgned to another file. Either delete 
the exlstlng file or use another file specificat~on. 
- 


F i l e c a n n o t f l t i n t o G E N C P M b u f f e r : f l l e n a n e . S P R 


GENCPM. There is not enough memory to generate a system. 
- I F i l e e x i s t s , e r a s e i t 
I 
ED. The destination filename already exists when you arc plac- 
ing the destination file on a dlffcrent dlsk than the source. It 
should be erased or another dirk selected to receive the output 
file. 


F I L E I S RELDIONLY 
F i l e i s R e a d O n l r 


ED. T h e file specified in the command to invoke ED has the 
Read-Only attribute. ED can read the file so that you can 
examine it, but ED cannot change a Read-Only file. 
PUT. The file specified to recewe the output is a Read-Only 


- -- 
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Table A-1. (mntinued) 


Message 
Meaning 


FILENAMEERROR: 


LIB-80. The form of a source filename is invalid. 


F i l e n o t f o u n d . 
I FILE NOT FOUND - f i l e s ~ e c 


DUMP, ED, GENCOM, GET, PIP, SET. An input file that you 
have specified docs not exist. Check that you have entered the 
c o m a drive speufication or that you have the correct dlsk in 
the drive. 


F i p s t s u b m i t t e d f i l c m u ~ t 
b e 1 C O M f i l e . 


GENCOM. A COM file 13 expected as the first file in the com- 
mand tail. The only time GENCOM does not expect to see a 
COM filc in the first position of the command tail is when the 
NULL option is specified. 


LINK-80. A subsequent COMMON declaration is larger than 
the first COMMON declaration for the lndicatcd block. Check 
that the fils being linked arc in the proper ordcr, or that the 
modules in a library are in the proper order. 


HELP. HELP cannot find HEW.DAT file to process. 
I 


I l l e Y a l o ~ m r a n d t a i l ~ 


DIR. The command line has an inval~d format or option. 
- 


- CP/M 3 User's Guide 
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Table A-1. (continued) 


DIR Both a filespec with a drive specifier and the DRIVE option 
appears m the command. 


- 
- 


I l l e g a l f i l e n a m e . 


- I 
SAVE. 'lhcre is an error in the filespec on the command line. 


Message 
Meaning 


I l l e t a l Format V a l u e . 


DIR. Only SIZE and FULL options can be used for display 
formats. 


I l l e g a l G l o b a l l L o o a l O r ~ v e S ~ e c M i ~ i n t . 


I l l e l a l O p t i o n ~ ~ M o d i f i e ~ . 


DIR. An invalid option or abbreviation was used. 


- 


DATE. Date/time format is invalid. 


I n c o r r e c t f i l e S P e s l f i e a t i o n . 


- 
RENAME. f i e format of the filespec ts invalid. 


INOEXERROR: 
- 
- 


- 
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LINK-SO. The index of an IRL contains rnvalid information. 


I n s u f f i o i e n t M e r o r u 
INSUFFICIENT MEMORY: 


- 


GET, LMK-80, PUT, SUBMIT. There is not mough memory 
m allocate buffers, or them are too many levds of SUBMIT 
nntmg. 
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Table A-1. (continued) 
- 


I 
GENCPM. The character must be a number. 
I 


Message 
Meaning 


I n v a l i d A S C I I c h a r a c t e r 


SUBMIT. The SUBMIT Me contains an invahd character (OFFH). 


I n v a l i d c h a r a c t e r at l i n e N N . 


I n u a l i d c o n r a n d . 
1 


- 
- 


GET and PUT. The string or substrmg typed in the command 
line was not recognized as a valid command in the context 
used. 


I n v a l i d d e l i m i t e r . 


DEVICE, GET, PUT, SETDEF. The delimiter, [ I , = or space, 
- 
was not valnd at the location used. For example, a [ was 
used where an = should have been used. 


I N V A L I D D E S T I N A T I O N : 


PIP. An tnvalld drivc or device was specified. 


I N V A L I D D I G I T - f i 1 e S P L E 


PIP. An invalid hex digit has been encountered while reading a 
hex file. The hex file with the ,"valid hex dlgt should be cor- 
rected, probably by recreating the hex file. 


- 
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SETDEF. The specified drivc was not a valid dnve. Drives rec- 
ognized by SETDEF are . 
(default drive) and A to P. 
GENCPM, TYPE. Valid drives are A to P. 


- 
- 
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Tnblc A-1. (continued) 


Merrdge 
Meaning 


I n v a l i d d r i v e i l n o ~ e d 
a t 1 i n e N N ~ 


I 
GENCPM. Valid drives arc A to P. 
I 


( I n v a l i d d r i v e name ( U s e G. 
C , o r DL 
I 
COPYSYS, GENCPM. Only drives A, B, C and D are valid 
destxnatron drives for system generation. 


I n v a l i d F i l e . 
INVALIDFILENAME 
I n u a l i d f i l e name, 
I n u a l i d F i l e n a m e . 
Invalid f i l e ~ ~ e c i f i c a t i o n . 


ED, ERASE, GENCOM, GET, PIP, PUT, SET, SUBMIT, TYPE. 
The filename typed docs not conform to the normal CP/M 3 
file naming conventions. 


INVALID FORMAT 


PIP. The format of your PIP command IS illegal. See the 
dercrtption of the PIP command. 


INVALIDHEXDIGIT. 


HEXCOM. An invalid hex digit has been encountered while 
reading a hex file. The hex file with the invalid hex dlglt should 
be corrected by rccreatmg the hex file. 


I n v a l i d number. 


DEVICE. A number was u p c m d but not found, or the num- 
ber was out of range; numbers must be from 0 co 255. 


Table A-1. (continued) 


Merrage 
Meanmag 


DEVICE and GET. An option war expected and the string 
found was not a device optlon or was not val~d in the context 
used. 
SETDEF. The option typed in the command line is not a valid 
option. Valid opuons are DISPLAY, NO DISPLAY, NO PAGE, 
ORDER, PAGE, TEMPORARY. 


I n v a l l d o p t i o n a r r n o d i f ~ e r . 


DIR, GET, PUT. The option typed is not a valid option. 


I INVALID PARAMETER: 
I 
MAC, RMAC. An invalid assembly parameter was found in 
the input Ilne. The assembly parameters are printed at the con- 
sole up to the point of the error. 


I n v a l i d p a r a m e t e r v a r i a b l e a t l i n e N N . 


GENCF'M. The parameter variable doe nor exist. Check spelling. 


INVALID PASSWORD 
I n v a l i d p a s s w o r d o r p a s s w o r d s n o t a l l o w e d . 


ED, PIP. The specified password is incorrect, or a password 
war specified, but the file is not pasrword-protected. 


I I n u a l l d ~ h u s i e . 1 d e v i c e . 
I 
DEVICE. A ~hysical device namc was wpccted. The name found 
m the command string does not correspond to any physlcal 
device namc in the svrtem. 


1 I N V R L I D REL FILE: 
I 


UNK-80. The file indicated contains an invalid bit pattern. 
Makc sure that a W or U L lile has b 
n 
specified. 
1 


1 I n v a l i d RSX t y p e . 
I 
- 
GENCOM. Filetpe must be RSX. 


I n u a l i d S C B ~ f f s e t ~ 


GENCOM. The specified SCB is out of range. Ihe SCB offset 
range is DOH-64H. 


INVRLIOSEPRRRTOR 


PIP. You have placed an invalid character for a separator 
bemeen m a input filenames. 


INVALIDSOURCE 


PIP. An invalid drive or device was specified. AUX and CON 
arc the only valid devices. 


( I n v a l i d t y p e f o r ORDER o p t i o n , 
I 
SETDEF. Ihc type spedfied in the mmmrnd line was not COM 
or SUB. 


( I n v a l i d SYM f i l e f o r m a t 
I 


XREF. The filcnamc.SYM file mput to XREF is invalid. 


INURLIDUSERNUMBER 


PIP. You have spccificd a user number greater than 15. User 
numbers are in the range 0 m 15. 
- 
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Table A-1. (continued) 
- 


I 
GENCOM. GENCOM does not allow wildcards in filespecs. 
( - 


Message 
Mennmg 


I n u a l i d w l l d c a r d . 


RENAME. The filespec contained m invalid wildcard 
specification. 


I n v a l l d w i l d c a r d i n t h e FCBname o ~ t ~ ~ e f i e l d . 


- 


- 


MAINMOOULEERROR: 


LINK-80. A second main module was encountered. 


LOAD ADDRESSLESSTHAN 100. 


HEXCOM. The program origin is less than 100H. 
- 


GENCPM. The defined memory segment overlaps with other - 
seements. 


GENCPM. The defined memory segment overlaps another 
segment. 


~ e m o r u 
c o n f l i c t - s r g m e n t t r i s s e d . 


I MEHORY OVERFLOW: 
1 - 


- 


LINK-80. There is not enough memory to complete the link 
operation. 
- 


Table A-1. (continued) 


Merroge 
Meaning 


M i n i m u m n u m b m ~ o f b u f f e r s 1 5 1, 


1 
GENCPM. The fust drive must have at least one buffer defined I 


M i s ~ i n ~ D ~ 1 1 m i t e 1 0 r U n ~ r ~ o 9 n i z r d O c t i o n ~ 


ERASE. The ERASE command line format is invalid. 
I 


( Missins Parameter variable at line NN. 


GENCPM. The line is missing a variable name. 


M i s s i n g l e f t P a r e n t h e s i s , 


GENCOM. The SCB option must be endosed by a leh 
parenthesa. 


Missins r i l h t ~ a r e n t h e 3 i s . 


GENCOM. The SCB option is not enclosed with a righa 
oarenthesrs. 


GENCOM. The SCB optlon requires a value. 


More than f o u r d r i u c s s + e c i I i e d d 


SETDEF. More than four drives were specified for the drwe 
search chain. 


M U L T I P L E D E F I N I T I O N : 


LINK-80. The specified symbol is defined in more than one of 
the modules being linked. 
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~ a b k 
A-I. 
(continued) 


Merroge 
Meaning 


USER. You specified a number greater than fifteen for a user 
area number. For example, if you type USER 18, the screen 
display4 18?. 


p i r e e t o r r l a b e l e x i s t s . 
I 
SHOW. The LABEL option was requested but the disk has no 
label. 


I No d i r e c t o r 7 .Pace 


NODIRECTORY SPACE - f i l c 5 ~ e C 


COPYSYS, GENCOM, MAC, PIP, RMAC, AND SAVE. There 
is not enough directory space for the output fie. Use the ERASE 
mmmvld to remove m e e s s a y fils on the dlsk and try again. 


SAVE. There is not enough space on the disk for the output 
file. Use the SHOW command to display the amount of dnsk 
space left and use the ERASE command to remove unnecessary 
files from the dsk, or use another dlrk with more file space. 


No f i l e 
NO F I L E : 
N O F I L E - f i l r S P e c 


DER, EERASE, LIB-80, LINK-SO, PATCH, PIP, RENAME, TYPE 
The specified file cannot be found m the specified drive($). 


No HELP.HLP f i l e on t h e d e f a u l t d r i v e . 


HELP. The file HELP.HLP must be on the default drive. 
I 
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DUMP. The file you requested does not exist. 


No s c s o r r 


Table A-1. 
(continued) 


There is not enough memory available for loading the specrfied 
program. 


N o m o d i f i e r f o r t h i s o ~ t i . n l 


- 


GENCOM. A modifier was specified bur none rs required. 


NO UODULE: 


Message 
Meaning 


NO I N P U T F I L E PRESENTONDISK 


LIB-80. The indicated module cannot be found. 


No more s p a c e z n t h e h e a d e r ~ o P R S X S 
o r S C 6 


initialization, 


GENCOM. The header has room for only 15 entries, or the 
combrnatian of RSXs and SCBs exceed the maximum. 
1 


SET. Specify an option. 


No PRN f i l e l 


XREF. The file filename.PRN is not present on the specified 
drive. 


No R r e o r d s E u l s t 


DUMP. Only a directory entry exists for the file. 


Table A-1. (continued) 


Message 
Meanfng 


NO s o u r c e f l l e o n d l s K . 


COPYSYS. The file CPM3.SYS is not on the disk specified. 


N O S O U R C E F I L E PRESENT: 


MAC, RMAC. W e sour= file cannot be found on the specified 
dnve. 


( NO SPACE 
I 


SAVE. There is no space in the directoty for the filc being 
wnffen. 


No ' S U B ' f i l e f o u n d . 
I 


SUBMIT. The SUB file typed in the mmmand line cannot be 
found in the drive search Drocess. 


N O s u c h f i l e t o rename. 
I 


RENAME. The filc to be renamed does not exist on the spcci- 
fied drive($). 


No SYM f i l e 


XREF. The file filename .SYM is not present on the specified 
drive. 


I NON-SYSTEM F I L E C S ) E X I S T 
I 


DIRS. If nonsystem (DIR) files reride on the specified dnve, 
DIRS dis~lays this message. 


- 
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Table A-1. (continued) 
- 


Messsge 
Meanmg 


Not enoush a u a l l a b l e s e m o r u . 
- 
Not Enough Menorv 
Not Enough M e m o l l f o r S o r t . 


DIR, INITDIR. There is not enough memory for data or sort 
buffers. 


Not enough room I" d i r e o t o r ~ . 


INITDIR. There is not enough remaining directory spa- to 
allow for the date and time extension. 


- 


I 
PIP. A disk has the wrong format or a bad sector. 
I 


PIP. PIP cannot find the specified file. 


Not renamed, f i l e s p e c read o n l y . 
- 
- 
- 
Option o n l y f o r d r i v e s . 


SET. The spec~ficd option is not valid for filer 


RENAME. The spcified file cannot be renamed because it is 
Read-only. 


OPENFILENONRECOVERABLE 


- I O ~ t i o n r e q u i r e s a f i l e r e r e r e n c e . 
I 
- 
SET. The specified option requires a filespec. 


0°C of d a t a S P a E e l 
- 
COPYSYS. The destination drive ran our of space dur~ng the 
transfer of the CPM3.SYS file. 


A CP/M 3 Mnslgca 
CP/M 3 Usdr Guide 


Tsblc A-1. 
(continued) 


Message 
Meaning 


Options n o t r r o u P e d t o l r t h e r . 
I 
DIR. Options can only be spcclficd within one set of braken. ( 


O u t p u t F i l e E x i s t s t E r a s e i t , 


The output file specified must not already exist. 


1 OUTPUT F I L E READ ERROA; 
I 
MAC, RMAC. An output file cannot be written properly, 
probably because the disk is full. U9e the ERASE command to 
delete unnecessary files from the disk. 


1 OVERLAPPING SEGMENTS: 
I 


LINK-80. LMK-80 amrnpted to wrwe a segment into memory 
already used by another segment. 


P a l e a n d n o p a r e o p t i o n s e l e c t e d , 


1 N. .age 
I" e f f e c t . 


I 
SET. The preceding options are mutually exclusive. 


I P a r a m e t e r E r r o r 
I 
SUBMIT. Within the SUBMIT file of crne SUB, valid parame- 
ters are $0 through $9. 


P a s s w o r d E r r o r . 


DUMP, ERASE, GENCOM, TYF'E. The password is mcorren. 


P ~ Y S I E ~ ~ 
D e v i c e D o e ~ 
N o t E x i s t , 


DEVICE. The specified physical device is nor defined ~n the 
system. 


- 
Table A-1. (coatind) 


Message 
Meaning 


P o s ~ i b l e 
i n c o m ~ a t i b l e 
d i s k format. 


COPYSYS. Thc system disk a d the output disk have different 
formats. 
- I PROCRRM INPUT ICNORED. 
I 
SUBMIT. Thts message is preceded by "WARNING". The 
SUBMIT filc contains a line with <, and the program does not 
require addittonal input. 


PUT. This pmmpt occurs when a program requests input while 
running a PUT FILE [NO ECHO] command. 


PUT. The PUT output file war erased and muld not be closed. 


QUITNOTFOUND 


PIP. Thc string argument m n Q paramenr was not found in 
your input file. 


I Randon R e a d 
I 
SUBMIT. An error occurred whm reading the temporary filc 
uscd by the SUBMIT command. 


GENCOM, SET. The drive or file specified is write-prond. 


Read e r r o r 


TYPE. An error occumd when reading the file specified m the 
TYPE command. Check the disk and w rain. 
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Table A-1. 
(continued) 


GENCPM. An error occurred while attempting to read the file 
specified by filespec. 


R e a d i n l H E L P . H L P i n d e w 


HELP. An error occurred while reading HELP.HLP. Copy the 
- 


HELP.HLP file from the system disk. 


RECOROTOOLONG 
I 
PIP. A HEX record exceeds 80 characters in a file being copied 
with the [HI option. 


R r s u i r e r CP/M 3.0 o r h i g h e r , 


DATE, DEVICE, DIR, ERASE, GENCOM, HELP, INITDIR, 
PIP, SET, SETDEF, SHOW, RENAME, TYPE. ?his vcrsson of 
the util~oi must only be run under CP/M 3.0 or hieher. 


A 1 0 D I S K 


PIP. The dcstlnation drive is set to Read-Only and PIP cannot 
write to it. 


R l O F I L E 


PIP. The destination file is set to Read-Only and PIP cannot 
write to it. 


S o r t S t a c k O v e r f l o w 


DIR. There is not enoueh mcmooi avarlable for the sort stack. I 


Tnblc A-1. (continued) 


Messdge 
Meaning 


S o u r c e f i l e i s > n c m r n ~ l e t e ~ 


GENCPM. GENCPM cannot use your CP/M 3 system source 
file. 


SOURCEFILEREAOERRORl 


MAC, RMAC. The IOU~CF file cannot be read properly by MAC. 


1 SOURCE FILENAME ERROR: 


MAC, RMAC. The form of the source filename a invalid. 


STARTNOTFOUNO 


PIP. The string argument to an S parameter cannot be found rn 
the source file. 


S r n b o l T a b l e o u e r f l o w 


XREE. No space is available for an attempted symbol allocation. 


Srmbol T a b l e r e f e r e n c e o u e r f l o w 


XREF. No space is available for an attempted symbol reference 
allocation. 


SYNTAXERROR: 


LIB. The LIB-80 command is not properly formed. 


Too m a n y e n t r i e s i n I n d e x T a b l e s 
N o t enough remorv 


HELP. There is not enough memory avatlable to hold the topic 
tabk while cmating HELP.HLP. 


Table A-1. (continued) 


M c r ~ g e 
Meminx 


T o p i e : 


X X X X X X 
N o t f o u n d . 


HELP. The topic 
does not uist m the HELP.HLP 


file. HELP displays the topics available. 


1 T o t a l f i l e s i z e exceed-. 
I 
GENCOM. The output file exceeds the maximum allowed. 


T r v 'PAGE' o r 'NO PAGE' 


I 
TYPE. The only valid option is PAGE or NO PAGE. 
I 


I U n a b l e t o a l l O E . t e D a C a d e b l o c K i n I b u f f e r s ~ a o e , 
I 


GENCPM. Them is not enough $pace left in generated system 
to allocate a data deblocking buffer. 


GENCPM. There is not enough space left in 
system 
to allocate a dlrcctory deblocklng buffer. 


U n a b l e t o a l l o e a t e s p a c e f o r hash t a b l e * 


GENCPM. There is not enough contiguous memory to allocate 
space for the hash table in the 
system. 


U n a b l e t o c l o s e H E L P . D R T . 
/ U n a b l e t o c l o s e HELP.HLP, 


HELP. An error occurred while closing file HELP.HLP or 
HELP.DAT. There mrght not be enough dtsk or directory space 
on the dnvc. 


Table A-1. 
fcontinuedl 


Message 
Meaning 


U n a b l e t o f i n d f i l e H E L P . H L P . 


HELP. HELP requires HELP.HLP file to operate. Copy it to 
your default drive from your CP/M 3 system disk. 


U n a b l e t o MaKe HELP.DAT. 
U n a b l e t o NaKe HELP+HLP. 


HELP. There is nor enough space on the dlrk for HELP.HLP 
or HELP.DAT, or the files are Read-Only. 


U n a b l e t o o p e n : f l l e n a m e e S P R 


GENCPM. The filc specified cannot be found on the default 
drive. 


UNBALANCEDMACROLIBRARY+ 


MAC, RMAC. A MACRO defininon was stand within a macro 
library, but the end of the file was found in the library before 
the halanclng ENDM was encountered. 


UNDEFINEDSTART SYMBOL: 


LJNK-80. The symbol spenfied with the G swltch is nor defined 
in any of the modules being linked. 


UNDEFINEDSYMBDLS: 


LINK-SO. The symbols following this message are referenced 
but not defined ~n any of the modules being Imked. 


UNEXPECTEDENDOF H E X F I L E - f i l e s ~ e c 


PIP. An end-of-file was encountered before a termmation hex 
record. The hex filc wtthout a termination record should he 
corrected, probably by recreating the hex file. 
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I UNRECOGNIZED I T E N : 
I - 


Table A-1. (continued) 
- 


LINK-80. An unfamiliar bit pattern has been scanned and - 
ignored by LINK-80, 


Message 
Meoning 


U n r e c o g n i z e d d r i v e . 


SHOW. The specified drive is not valid. Valid drives are A to 
P. 


U n r e e o l n i r e d i n p u t . 


SHOW. Ihe SHOW command line has an invahd format. 
I - 


- 


GENCOM and SHOW. An option typed m the command line 
is not valid for the command. 


USER ABORTED 
I 
PIP. You stopped a PIP operation by presslag CTRL-C. 
I 


- 
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PIP. When copying with the V option, PIP found a difference 
when rereading the data just wrlnen and comparing it to the 
data in m memory buffer. 


- 
- 
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Table A-1. 
(continued) 


Mersoge 
Meoning 


W r i t e e r r o r 


XREF. This message a preceded by filcnamc.XRF and indicates 
that no disk space is available, or no directory space exlsts on 
the spec~fied drive. 


W r i t e p r o t e c t e d ? 


COPYSYS. The drive or disk to which the system is to be 
wrinen is Read-Only. 
- 
I ~ ~ i t i n g f i l e : 
f i l e s p e c 
I 


GENCPM, HELP. An error occurred while attempting to wrltc 
the file specified by filespec. 


Wrong P a s s w o r d . 
- 
SET. The speciiied password is incorrect or invalid. 
I 


- 
- 


- 
End of Appendix A 


GENCPM. A memory segment cannot have zero length. 


O F F F F H i s an l n v a l l d v a l u e ~ n t h e D P H d l r e e t o r u BCB 
a d d r e s s f i e l d . 


- 
- 
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GENCPM. Th~s value is allowed only in the DTABCB field. 


SID. SID has enmunrcrcd an error. 


- 
Appendix B 
ASCII and Hexadecimal Conversions 


ASCll stands for American Standard Code for Information Interchange. The code 
- 
contains 96 printing and 32 "on-printing charanen used to store data on a disk. 
Table B-l defines ASCll symbols, then Table B-2 lists the ASCll and hexadecimal 
convcn~ons. The table lncludes binary, dccnmal, hexadecimal, and ASCll conversions. 


Table 6-1. ASCII Symbols 
- 


FF 
form-feed 
US 
unit separator 


YT 
vertical tabulation 
- 


Symbol 
I 
Meaning 
I 
Symbol 


- 
- 
- 
- 


- 
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Meanin8 


- 
. 
s 


BS 
backspace 
HT 
horizontal tabulation 
CAN 
cancel 
LF 
line-feed 


CR 
carriage rcmrn 
NAK 
negative a&owledg. 


DC 
device control 
NUL 
null 
DEL 
delete 
RS 
record separator 
DLE 
data link escape 
SI 
shift in 
EM 
end of medium 
SO 
shift out 


;% 


enquiry 
SOH 
start of headlog 


end of transmission 
SP 
space 


ESC 
escape 
STX 
stan of text 


ETB 
end of transmission 
SUB 
substitute 


ETX 
end of text 
SYN 
synchronous idle 


ACK 
adaowledge 
FS 
file separator 
BEL 
bell 
GS 
~ O U D 
aeoarator 
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Table B-2. ASCII Conversion Table 


I Binam 
I 
Decimal 
I 
Hexadecimal 
I 
ASCII 
I 


0 
NUL 


1 
SOH (CTRL-A) 


2 
STX (CTRL-B) 


3 
ETX (CTRL-C) 


4 
EOT (CTRL-D) 


5 
ENQ (CTRL-E) 


6 
ACK (CTRL-Fl 
BEL (CTRL-G) 
BS 
(CTRL-H) 


HT (CTRL-I) 
LF 
(CTRL-J) 


VT (CTRL-K) 
FF 
(CTRL-L) 


CR 
(CTRL-M) 


SO 
(CTRL-N) 


SI 
(CTRL-0) 


DLE (CTRL-P) 
DCl (CTRL-Q) 
DCZ (CTRL-R) 
DC3 (CTRL-S) 
DC4 (CTRL-T) 
NAK (CTRL-U) 
SYN (CTRL-V) 
ETB (m-w) 
CAN (CTRL-X) 
EM (CTRL-Y) 
SUB (CTRL-2) 
ESC (CTRL-[) 
FS 
(CTRL-\) 


GS 
ICTRL-11 


RS 
~CTRL-:i 


US 
(CTRL-) 


(SPACE) 
, 


Table B-2. lcantinued) 


Binmy 
I 
Dectmal 
1 
Hexadecimal 
1 
ASCII 


0100110 
38 
26 
& 
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- 


- 
- 


- 
- 
- 
- 


- 
- 
- 


- 
- 
- 


Table B-2. (cmhued) 
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Binary 
I 
Decimal 
Honrdecimal 
I 
ASCII 


1001100 
76 
4C 
L 


1001101 
77 
4D 
M 


1001110 
78 
4E 
N 
1001111 
79 
4F 
0 
1010000 
80 
50 
P 
1010001 
81 
51 
1010010 
82 
52 
1010011 
83 
53 
:: 


1010100 
84 
54 
T 
1010101 
85 
55 
U 


1010110 
86 
56 
V 


1010111 
87 
57 
W 
1011000 
88 
58 
X 
1011001 
89 
59 
Y 


1011010 
90 
5 A 
Z 


1011011 
91 
5B 
[ 


1011100 
92 
5C 
\ 
1011101 
93 
5D 


1011110 
94 
SE 
! 


1011111 
95 
SF 
< 
1100000 
96 
60 
1100001 
97 
61 
a 
1100010 
98 
62 
b 
1100011 
99 
63 
c 


1100100 
100 
64 
d 
1100101 
101 
65 
e 


1100110 
102 
66 
f 
1100111 
103 
67 
g 


1101000 
104 
68 
1101001 
105 
69 
1101010 
106 
6A 
j 


1101011 
107 
6B 
1101100 
108 
6C 
I 
1101101 
109 
6D 
m 


1101110 
110 
6E 
1101111 
111 
6F 
o 


1110000 
112 
70 
P 
1110001 
113 
71 
9 


Tnblc Bf. (continued) 


/ 
B~narv 
I 
Dccimnl 
I 
Hexadecimal 
I 
ASCII 


Y 


{ 
I 
I 


DEL 


End of Appendix B 
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Appendix C 
Filetypes 


CP/M 3 identifies every file by a unique file specification, which consists of a drive 
specification, a filename, a filetype, and an optional password. The filetype 1s an 
optional three-character ending separated from the filename by a penod. The filetype 
generally ~ndicates a rpedal kind of file. The following table lists common filetypes 
and their meanings. 


Table C-1. Common Filetype 


Tme I 
~eaning 


ASM 
Assembly language source file; the CP/M 3 assemblers assemble or 
translate a type ASM file into machine language. 


BAK 
Back-up file created by ten editor; the editor renames the source filc 
w~th thls filetype to indicate that the orignnal file has been processed. 
The original file stays on disk as the back-up file, so you can refer 
to it. 


BAS 
CBASIC program source file. 


( COM 
8080 executable file. 
I 


1 ERL 
PaxaVMT+ " relocatable filc. 
I 


I HU( 
Program file in hexadecimal format. 
I 


1 INT 
CBASIC program intermediate language file. 
I 


1 lRL 
Indexed REL file produced by LIB. 
I 


- 
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- 


LIB 
Used by MAC and RMAC for macro Ilbranes. W e ED R command 
mads filer of type LIB. The ED X command writer files of type LIB. 
Pnnrablc filc displayable on console or pnntcr. 
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Table GI. (continued) 


M e I 
Meaning 
OVL 
Program overlay file. PUI-80 compiler overlays files; you can create 
overlay files with LINK-SO. 


PAS 
Pascal/MT+ source program filetype. 


PUI-80 source program filetype. 


PRL 
Page Relocatable file; a file that does not require an absolute seg- 
ment. It can be relocated in any Page Boundary (256 Bytes). 


PRN 
Printable file displayable on console or pnntcr. 


REL 
Relocatable file produced by RMAC and PUI-80 that can be linked 


1 
by LINK-80. 


SPR 
System Page Relocatable file; system fils required to generate 
CP/M 3, such as BNKBDOSSPR, BDOSSPR, BIOSSPR, and 
RESBDOS.SPR. 


SUB 
Fllqpe required for submit file containing one or more CP/M 3 
mmmands. The SUBMIT program executes commands in files of 
type SUB, providing a batch execution mode for CP/M 3. 


SYM 
Symbol table file. MAC, RMAC, and LINK-80 output files of type 
SYM. SID and ZSlD read files of type SYM. 


SYS 
System file for CP/M 3. 


TEX 
Source file for TEX-80", the Digital Research text formatter. 


TOK 
Pascal/MT+ intermediate language file. 


XRF 
Cross-reference file produced by XREF. 


$$$ 
Tem~orarv file 


End of Appendix C 


Appendix D 
CP/M 3 Control Character Summary 


Table D-1. Nonbmked CP/M 3 Control Characters 


Chamctm 
Meonmg 


CTRL-C 
Terminates the executing program and redisplays the system 
pmmpt, provided the cursor is at the begnning of the command 
line. Also, xf you halt scrolling with CTRL-S, you can terminate 
the program with a CTRL-C. 


CTRL-E 
Forces a physical carriage m r n but does not rend the mm- 
mand line to CP/M 3. Moves the cursor to the beginnrng of the 
ncn line without erasing your previous input. 


CTRL-H 
Dclms a character and moves the cursor left one character 
poritlon. 


CTRL-I 
Moves the cursor to the next tab stop. Tab stops are automati- 
cally set at each clghth column. Has the same effect as pressing 
the TAB key. 


CTRL-J 
Sends the command hne to CP/M 3 and m r n s the cursor to 
the lek of the current line. Has the samc effect as a RETURN 
or a CTRL-M. 


CTRL-M 
Sends the command line to CPlM 3 and returns the cursor to 
the left of the current Ime. Has the samc effect as a RETURN 
or a CTRL-J. 


CTRL-P 
Echoes all console activity to the printer. The first time you type 
CTRL-P, CP/M 3 rlng a bell at your mnsole. You can use 
CTRL-P after you halt scrolling with CTRL-S. A second CTRL- 
P ends printer echo; no bell rings. CTRL-P has no effect if your 
system does not include a pnntcr. 


Table D-1. 
(continued) 


I Character 
I 
Meantng 


CTRL-R 
Places a # at the current cursor location, moves the cursor to 
the next line, and dlsplayr any ~artlal command you typed so 
far. 


CTRL-S 
Stops screen scrolling. If a display scrolls by too fast for you to 
read it, we CTRL-S. CTRL-Q restarts screen scrolling. 


CTRL-U 
Discards all the characters in the command line, places a # at 
the current cursor position, and moves the cursor to the n u t 
command Ime. 


CTRL-X 
Dlscards all the characters in the command Ime, and moves the 
cursor to the beginning of the current line. 
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Table D-2. Bvlkcd CP/M 3 Lincsditing Control Charactem 


CTRL R 
Move. the cursor to the hcennlng of rhc command lnnc warhout 
hav~ng anv rrfrri on rhc rontcnt5 of the l~nc If the .urror us ~t 
- 
thr brgnnlng, C1RL.B moves 11 to the cnd of rhc lhnc 


- 


CTRL-C 


Choroner 
1 
Meantng 


CTRL-A 
Moves the cursor one character to the left. 


CTRL-E 


CTRL-F 


CTRL-G 


CTRL-H 


CTRL-I 


CTRL-J 


CTRL-K 


CTRL-M 


Terminates theexeating progam and redrsplays the system prompt, 
provided the cursor is at rhe beginning of the command line. Also, 
if you halt scrolling with CTRL-S, you can terminate the program 
wlrh a CTRL-C. 


Forces a physical carriage return but docs not send the command 
line to CP/M 3. Moves the cursor to the beginning of the next 
line without erasing the previous input. 


Moves the cursor one character to the right. 
I 


Ddetes the character indscated by the cursor. The cursor docs not 
move. 


Delete a charam and move the cursor left one character position. I 
Moves thccursor to thenext tab stop. Tabstops are automatically 
set at each eighth column. Har the same effect as pressing the 
TAB key. 


Sends the command line to CP/M 3 and returns the cursor to the 
beglnnlng of a new Ime. Has the same effect as a RETLTRN or a 
CTRL-M keystroke. 


Deletes to the end of the llnc from the cursor. 
I 


Sends the command line to CP/M 3 and returns the cursor to the 
beglnnlng of a new line. Has the same effect as a RETLJRN or a 
CTRL-J keystroke. 
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Table D-2. (continued) 
- 


Character 
I 
Meaning 


CTRL-P 
Echoes all mnsolc activity to the printer. The first time you type 
CTRL-P, CP/M 3 rings a bell at your console. You can use CTRL- 
P after you halt scrolling with CTRL-S. A semnd CTRL-P ends 
printer echo; no bell nngs. CTRL-P has no effect if your system 
does not lndude a printer. 


CTRL-R 
Retypes the mmmand line. Places a # at the current cursor loca- 
tion, moves the cursor to the next line, and retypes any partial 
command you typed so far. 


CTRL-S 
Stops screen scrolling. If a display scrolls by too fast for you to 
read it, type CTRL-S. CTRL-Q rcsram screen scrolling. 


CTRL-U 
Discards all the characterr in rhc command line, places a # at the 
current cumor pos~tlon. and mover rhc cursor to the next line. 
However, you can urc a C T R L W to recall anv charancrs that 
were to the left of the cursor when you pressed CTRI.-U. 


CTRL-W 
Recalls and displays previously e n t e d command line both at the 
operating system level and in executing programs, if the CTRL- 
W is the first character entered after the prompt. CTRL-1, CTRL- 
M, CTRL-U, and RETURN define the command line you can 
recall. If the command line contains characters, CTRL-W moves 
thecursor to the end of the command line. If you press RETURN, 
CP/M 3 executes the recalled command. 


CTRL-X 
Discards all the characters left of the cursor and moves the cursol 
to the beginning of the current bne. CTRL-X saves any characterr 


End of Appendix D 
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Appendix E 
User's Glossary 


ambinuous filmamc: Filename that contams either of the CP/M 3 wildcard charac- 
t m . ' or ', ln rhc prlmarv filename or the filcrypc or both. W e n you usc w~ldcard 
charancrs, you create an amblguour filr,pcc and can carllv rcfcrcncc more than one 
CI'M 3 file. Srr Scctlon 2 ur thlr manual 


applications pmgnim: Program that solves a specific problem. Typical applications 
programs are bus~ness accounting packages, word processing (editing) programs, and 
mailing hst programs. 


argument: Symbol indicaung a place into which you can substitute a number, letter, 
or name to give an appropriate meaning to a command line. 


ASCII: 'Ihr Amcrmc~n Standard Codc tor lnform~r8on lnrcrchangc 8 % a standrrJ 
coJc for rcprcrcnrarlon of numbers, Ictrcrr, and symholr. An AS('II text file tr r hlr. 
that can he tnrrlltahly d!rpla\.rd on the rtdco ~ r c c n 
oc prnnrrd on papcr. (cr Appm- 


dtx R. 


amibute: Fxle character~stcc that can be set to on or off. 


back-up: 
Copy of a dirk or file made for safe keeping, or the creation of the back- 
up disk or file. 


bit: Switch ~n memory that can be set to on (1) or off (0). Bin are grouped into 
bytes. 


block: Area of disk. 


bmnnsp: Process of loading an operating system into memory. Bootstrap proce- 
dures vary from system to system. The bwt for an operating system must be custom- 
!red for the memory sire and hardware environment that the operating system man- 
ager. Typically, the boor is loaded automatically and executed at power up or when 
the computer is reset. Sometimes called a "cold start." 
- 


buffer: Area of memory rhat temporarily stores data during the transfer of infor- 
matlon. 
- 
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built-in commands: Commands that permanently reside ~n memory. They respond - 
quickly because they are not accessed from a disk. 


byts: Unit of memory or disk storage containing e~ght bits. 
- 


draraaer string: Any combination of letters, numbers, or special characters on your 
keyboard. 
- 


command: Elements of a CP/M 3 command line. In general, a CP/M 3 command 
has three parts: the command keyword, the command tall, and a carriage return 
keystroke. 
- 


command file: Series of coded machrne executable instructions stored on disk as a 
program 615 invoked in CP/M 3 by typing the command keyword next to h e system 
prompt on the console. CP/M 3 command files generally have a filetypc of COM. - 
Files are either command files or data files. Same as a command program. 


command keyword: Name that identifies an CP/M 3 command, usually the primary - 
filename of a file of rypc COM, or a built-~n command. The command keyword 
precedes the command tail and the carnage return nn the command line. 


command syntax: Statement that defines the correct way to enter a command. The - 


correct structure generally indudes the command keyword, the command tad, and a 
carriage return. A syntax line usually conrams symbols that you should replace with 
actual values when you enter the command. 
- 


command tail: Part of a command that follows the command keyword in the com- 
mand line. The command tail can include a drive spec~ficarion, a filename and/or 
filetype, and apt~ons or parameters, bur cannot exceed 128 characters. Some com- - 


mands do not require a command tail. 


coneatmate: 
Term that describes one of PIP'S operattons that combines two or - 
more separate files into one new file ~n the specified sequence. 


console: Primary mpur/output devtce. The console consists of a listlng device such - 
as a screen and a keyboard through wh~ch the user communicares with the operating 
system or appl~catlonr program. 


- 
control character: Nonprindng character combination that sends a stmple com- 
mand to CP/M 3. Some control characters perform hne editing functions. To enter a 
control character, hold down the CTRL key on your term~nal and rtrlke the charac- 
ter key specified. SK Appendix D 


amor: Onc-character symbol that can appear anywhere on the console screen. The 
cursor indicates the position where the next keystroke at the console will have an 
effect. 


data file: Nonexecutable collection of similar cnformation that genrrally requires a 
command file to manipulate it. 


dcfault: 
Currcnrlv srlcctcd d ~ r k Jrwr andor uqcr number Any command t h . ~ 
doc\ 


no, ,pr\th. a A s k drnr or a u 
~ 
r 
ndmhcr rcfcrcnro the dcfaulr dtrk drtrc and urcr 


numhcr. W c n CI'\1 3 is first ~nvokcd. thc drf~ulr dlrk drove 1s dmc A. and rht 
default urer number 1s 0, until changed wnh the USER command. 


delimiter: Special characten that separate different items in a command line. For 
example, m CP/M 3, a colon separates the drive spec from the filename. A period 
separates the filename from the filcrype. Brackets separate any optsons from then 
command or filespec. Commas separate one item 
an option list from another. All 
of the preceding special characters are del~maerr. 


directory: Ponton of a disk that contains descriptions of each file on the dlsk. In 
response to the DIR command, CP/M 3 dtrplays the filenames stored in the directory. 


DIR attribute: File attribute. A file with the DIR attribute can be displayed by a 
DIR command. The file can be accessed from the default urer number only. 


disk, diskette: Magnetic media used to store information. Programs and data are 
recorded on the dlsk m the same way that music a recorded on a cassette rape. The 
term diskette refers to smaller capacity removable floppy dekettcs. Dlsk can refer to 
a dakerre, a removable cattrtdge dirk, or a fixed hard dak. 


disk drive: Peripheral device that reads and writes on hard or floppy dirks. CP/M 3 
assigns a letter to each drlve under its control. For example, CP/M 3 can refer to the 
drives m a four-drive system ar A, B, C, and D. 
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editor: Ut~llty program that creates and modtfies text files. An edltor can be used 
for crcatton of documents or creat~on of code for computer programs. The CPlM 3 
editor is invoked by ryp~ng the command ED next to the system prompt on the 
console. (See ED m Section 6 of this manual). 


executable: Ready to be run by the computer. Executable code 8s a series of instruc- 
tions thar can be carrlcd out by the computer. For example, the computer cannot 
execute names and addresser, but ~t can execute a program that prlntr all those 
names and addresses on mailing labels. 


execute a program: Start a program executing. When a program is running, the 
compurrr !s executing a sequence of inrtnrcr~ons. 


FCB: See File Control Block. 


file: Collecrion of characters, instructions or data stored on a dsk. ?he user can 
creare files on a disk. 


File Control Block: Structure used for accessing files on disk. Conra~ns the drive, 
filename, filetype and other tnformatlon describing a file to be accessed or created on 
rhe dcsk. 


filename: Name ass~gned to a file. A filename can ~ndude a primary filename of 1-8 
characters and a filetype of 0-3 characters. A persod separates the primary filename 
from the filetype. 


hk rpedcation: Unique file ~dentifier. A complete CP/M 3 file specification indudes 
a dlsk drwe spcc~ficat~on followed by a colon (d:), a primary filename of 1 to 8 
characters, a period, and a filetype of 0 to 3 characters. For example, b:examplc.tex 
is a complete CP/M 3 file rpecificarion. 


filetype: Extens~on to a filename. A filetype can be from 0 to 3 characters and must 
be separated from the primary filename by a period. A filctype can tell something 
about the file. Certain programs require thar files to be processed have certain file- 
types (see Appendtx C). 


floppy disk: Flexible magnetic d~sk used to store information. Floppy dirks come in 
5 114- and 8-inch diameters. 


hard disk: Rwd, qlatter-like, magnctlc dirk sealed m a contamer. A hard disk 
stores more information than a floppy dak. 


- hardware: Physical components of a computer. 


h a file: ASCII-printable representation of a command (machine language) file. 
- hexadecimal notation: 
Notation for the base 16 number system using the symbols 
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, and F to.rcprcsent the sixteen digits. 
Machrnc code is often converted to hexadecimal notation because it can be easily 
- represented by ASCII characters and therefore printed on the console screen or on 
paper (see Appendix B). 


input: Data going into the system, usually from an operator typing at the terminal 
- or by a program reading from the disk. 


interface: Object that allows two independent systems to communicate with each 
- other, as an lnterface between hardware and software in a microcomputer. 


VO: Abb-lation 
for inputloutput. 
- keyword: 
See command keyword. 


kilobyte: 1024 bytes denoted as 1K. 32 kilobytes equal 32K. 1024 k~lobytes equal 
- one megabyte, or over one million bytes. 


list device: Device such as a printer onto w h ~ h 
data can be listed or printed. 
- logical: Representation of something that might or might not be the pame in its 
actual physical form. For example, a hard dlsk can occupy one physical drive, and 
yet you can divide the available storage on it to appear to the user as if it were in 
- several different drives. These apparent drives are the logcal drives. 


megabyte: Over one millton bytes; 1024 kilobytes. See byte and kilobyte. 
- 


miaoprocnsor: Silimn chip that is the Central Processing Unrt (CPU) of the micro- 
computer. 
- operating system: Collect~on of programs that supervises the running of other pro- 
grams and the management of computer resources. An operatmg system provides an 
orderly lnpurioutput environment between the computer and its peripheral devices. 
- 


option: One of many parameters that can be part of a command tail. Use options 
to specsfiy additional condxtlons for a command's execution. 
- 
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output: Data that the system sends to the console or disk. 
- 


parmeter: Value in the command tail that prov~des addltlonal inhrmat~on for the 
command. Technrcally, a parameter is a requ1r.4 element of a command. 
- 


peripheral deviccs: Devices external to the CPU. For example, terminals, printers, 
and dirk dr~vcs are common peripheral devices that are nor pan of the processor, 
bur arc used in conjunction with it. 


physical: 
Actual hardware of a computer. The phyrlcal environment varies from 
computer to computer. 
- 


primary filename: Flrst 8 characters of a filename. The prlmary filename is a unique 
name that helps the user identify the file contents. A primary filename contains 1 to 
8 characters and can lndude any lemr or number and some special characters. The - 
primary filename follows the optional drive specificarron and precedes the optional 
filetype. 


program: Series of specially coded lnrtructtons that performs specific tasks when - 


executed by a computer. 


prompt: 
Characten displayed on the screen to help the user decide what the next - 


appropriate actlon is. A system prompt is a special prompt drsplayed by the operating 
svrrcm. The rvrrcm prumpt lnd~carri ru rhc user that rhc opcmnng svstcm rr ready 
ro arrrpt Input. Ihc CP M 3 rvrtrrn prompt mr an alphabcrtc rhrrrctcr lollowcd by 
an angle hrackcr. Thr al~hahcrlc character nnd~catcr rhc Jclault dr~vc. Somr appl~ca- - 


t~ons programs have their own special system prompts 


Read-Only: Attribute that can be ass~gned to a disk file or a d~sk drive. \Wen - 
asstgned to a file, the Read-Only attribute allows you to read from that file but not 
chanee it. When assiened to a dnvc. che Read-only attribute allows vou to read anv 
file on the disk, but prevents you from adding a new file, erasing or changing a file, - 
renaming a file, or wrltlng on the disk. The SET command can set a file or a drive to 
Read-Only. Every file and drive 1s either Read-Only or Read-Wnte. The default 
senlng for dr~ver and files 1s Read-Write, but an error in resetting the disk or chang- 
ing medla automat~call~ 
sets the drive to Read-Only until the error IS corrected. Files - 


and disk drrver can be set to either Read-only or Read-Write. 
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Rcad-W"te: 
Attribute that can be assigned to a dsk file or a disk drive. The Read- 


Write atulbute allows you to read from and mite to a specific Read-Write file or to 
any file on a dlsk that is in a drive set to Read-Write. A filc or drive can be set to 
either Read-Only or Read-Write. 


record: Collection of data. A file consists of one or more records stored on d~sk. 
An CP/M 3 record is 128 bytcs long. 


RO: See Read-Only. 


RW: 
See Read-Write. 


sMor: Portion of a disk track. There are a specified number of sectors on each 
track. 


sohare: Specially coded programs that transmit machine-readable instructions to 
the computer, as opposed to hardware, which is the a m a l physical components of a 
computer. 


soures filc: 
ASCII text file that rr an input file for a processing program, such as an 


editor, t e n formatter, or assembler. 


string: See character srting 


syntax: Format for entering a given command. 


qstem amibutc: File attribute. You can give a file the system attribute by using the 
SYS optlon in the SET command. A file with the SYS attribute is not dssplayed ~n 
response to a DIR command; you must use DlRS (see Section 5). If you give a file 
with user number 0 the SYS attribute, you can read and execute that file from any 
user number on the same drive. Use this feature to make your commonly used 
programs available under any user number. 


system prompf: Symbol displayed by the operating system indicating that the syr- 
tem a ready to receiv~ ~nput. See pmmpt. 


tmninal: See console. 


track: Concentric rings dividing a dirk. There are 77 tracks on a typical eight-inch 
floppy disk. 
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--key 
application: Apphcation designed for the "oncomputer-oncnted user. For 
example, a typical ~rn-key application 1s designed so that the operator needs only to 
turn on the computer, insert the proper program dlsk, and select the desired proce- 
dure from a selection of functions (menu) displayed on the screen. 


upward-atible: 
Term meaning that a pmgram m t e d for the previously released 


operatlng system (or compiler, etc.) runs under the newly released version of the 
same operating system. 


user number: Number from 0 m IS assigned to a file whm it is created. User 
numbers can organize files into sixteen file groups. 


utility: Tool. Program that enables the user to perform certain operations, such as 
copymg files, easing files, and editing files. Utilities are created for the convenience 
of programmers and users. 


wildc~rd characters: Special characters that give CP/M 3 a partcm m m a d whcn 
it searches the directory for a file. CP/M 3 recognizes two wildcard characterr, ? and 
'. me ? can be substituted for any single character in a filespec, and the ' can be 
substioltcd for the primary filename or the filetype or both. By placing wildcard 
characters in a filespec, you create an ambiguous filespec and can quickly reference 
one or more files. 


End of Appmdix E 
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CP/M PIUS command Summary 


H O W TO ENTER A 
CP/M PLUS COMMAND 


TO give CP/M PI"." . 
commanl. type a 


somprere command llne iollawing the CP/M 
Pl". 
system prompt. A > . 
A CP/M 
PIUS 


somana llnE 
consists of a oonmand. an 


opi~onal eonmane L m x I . Lnl a RETURN OC 
mTER *EyslloXe. 
The command is the name 


Of a 
to run. M oprlonnl cornnand 


t a l l can conslnt o t a a r i v e l e t t e r 
foliowed by ,y "colon, 
one or more file 


options. 
TO complete the 


command you nust press the REIURN or nn'ER 
key. 


CP/M PLUS FILE SPECIFICATIONS 


ThlS summary uses the foliowing symbols to 
designate the parts of a filespec. 


Symbol 
Meaning 


d: 
Represents the optional 
dl,"= spesrflsarlon, "hioh 
c a n b e a n y single 
.Iphabetlo 
oharasrer in 


the cange I 
through P. 


followed by a colon. 


filename 
Represents the required 
fllenane. *hi.h 
can be 


from l to 8 alphanumerlo 
characters. 


CP/M Plus Comand Sumnary 


S p b l 
Heanlng 


.tYP 
Represents the optional 
fllerype, vhrch can be 
from 0 to 3 alphanunerrc 
characters: separated from 
the filename by a p e r l d . 
I\ period does not precede 
the fllekype *hen the 
rlletype IS named alone I" 
the t e x t of LhlS "omand 
BYmn"Y. 


V n l l d comblnarions of the elemenra of a 
rllespes are shown belor: 


COMMAND SUMMARY CONVENTIONS 


me c o m n a 
. ~ ~ h ~ b ~ r i ~ ~ l l ~ 
liars 


eaoh CP/M Plus command using the f o l l a l n g 
special sy.Do1. 
to define cornand .ynt.x, 


Symbol 
Il..oing 


0 
optional iten 


I 
'or' bar, .eparatss choic.. 
when 


Only on. option can b. "..a 
at a 


rim. 


n 
number 


cm, 
cnrtro, k.Y 


0 
option or an option 1i.e 


t m . 
RETUW or r n E R k.Y 
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srs 
system artrlbute; f ~ l e 
does nor 


a p p e a r " h e n d l r e s t o r y 
i s 


dlaplayed by OIR command 


DIR 
Diresmryattrlbute: flleappears 
In response l o DIR ComCOAnd 
... 
man. rhe element can be repeated 
as many trnea oa you want 


wildcard: ceplaces a l l or Part of 
. 
fllenane and/or flletype; must 


be laat charaster in filename or 
filetype 
, 
*ilds..d; 
1ep1aoea any single 


Charaoter In me same poa1tion of 
a filename and/or filetype 


L I 
type square brackets to enclose an 
option list 


CerlainCP/HPlus o o m a n d s can be modified 
by oprlons added to the c o m a n d or f i l e 
SpeCiflCLllI.,". 
Optlonn are enclosed 1" 


square bracter.. 
The right-hand square 


bracket 1s optional. 
only one or two 


cnaiactors o f t h e option word are 
n e c e s s a r y to s p e s l f y a n o p t i o n . 
G e n e r a l l y , 
o p L l o n s c a n be grouped 


togethe., Beparared by somas or spaces i n 
the square brackets. 
This doe8 not apply 


r0 oprlons that OontradlsL each orher. 
Somerlmes the "hole comlnand t a l l 1s 
optional. 


CONTROL CHARACTERS 


=he €ollo*ing l i s t presents CP/M Plus 
control chaxacters an* their runcr,ona. 


Control 
Character 
Pun~tlon 


CTRL-& 
mves cursor one vharavter LO 
the l e f t . 
Uolka only i f your 


comC.uter 
has bank-sxltshed 


CTRL-8 
W v e s cursoc from beginning to 
end of command line and aac* 
*ithour affecting command. 
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CONTROL CHARACTERS (contlnued) 


control 
Character 
F Y ~ O L I O ~ 


CTRI.-C 
Stops executing proglslo when 
entered a l the ayatem prompt or 
a f t e r CTRL-8. 


CTRL-E 
F o r c e s a 
PhYE1C.1 
r e t u r n 


xlrhour sending command to CP/M 
Plus. 


CTRL-F 
I * o v e ~ cursor one Ehalacter ko 
the right. Banked system only. 


CTEL-G 
Deletes character 
a t current 


cursor positlo" I f 1" the 
lolddie of a 1,ne. 
Banked 


ayetern only. 


CTRL-W 


Delete character to the left of 
cursor. 


Same as the TAB key. 


"eves cursor to the left of the 
command Ilne and rends "omnand 
to CP/* PLUS. 
b ~ n e 
feed: same 


effect as RETURN. 


Deletes oharasrer a t cursor and 
all charasters to the right. 


seme as RETURN. 


shoe:, sonsole output to the 
list devloe. 


Restarts screen scrollrng 


Retypes the characters to the 
left of the cursor on . 
new 


h n e : updates the command line 
buffer. 


Updates the command llne buffer 
LO contain the chaiscfela to 
the lest of the cursor, deletes 
current line. 


Recalls prev,ovs command l i n e 
l i c n r r e n t 1,ne 
1 s empty; 


OtherwILe moves cursor to end 
Of Ilne. 
CTRL-J,-M,-R.-U 
and 


RETURN update the command llne 
buffer for recall vlth CTRL-W. 
Banked sysrern only. 


Deletes a11 0hara"Lers to the 
left of the cursor. 


CP/M PI". 
Command sumary 


COPYSYS 


COPYSYS COpleS the CP/M Plus system from a 
CP/M Plus system diskette to anorher 
diskette. 
The new dlskeree muat have the 


s a m e format a s the o r r g l n a l system 
diskette. 


DATE 


DATE 
DATE C 
DATE CONTINUOUS 


DATE time-speclfisatio" 
DATE SET 


Rlrpose: 


me DATE cornand 
lets you display and set 


the date and tine of day. 


*a.p1e.: 


A,DITE 


~ l s p i a y s 
the curcent date and rime 


I\,DIm Oa/14/82 1023010 


sets the dare and tlloe. 


IrDlTE SST 


Pzonpra for dare and tune entries. 
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DEVICE 


syntax: 


DEVICE 
DEYTCE NILHES 


DEVICE VALUES 
o=vrc= log1ca1-dev i x o ~ ~ ~ ~ x o ~ ~ b a u d - ~ a t e j 
DEVICE physlsal-dev fXDNINDXONbaud-rate) 
DEVICE logicill-de"=phyblcaI-dd" 
( 0 tion 


i .physlsal-dev foptionP.. . .I 


D N l C E loglsal-dev - NULL 
DEVICE CONSOLE [PACLCBI 
DEVICE CONSOLE ICOILUHNS-n.LINES-nl 


Purposei 


DEVICE d ~ s p l a y s aurrenr logioal devise 
abrlgnments and phyalcal device names. 


A>DE"lcB CRT 


Dlsplaye rhs attributea of the phyaisal 
device CRT. 


llrDBVleB mn 


display^ the assignmcnk of the logical 
devlce CON8 
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DEUCE (continued) 


DEVICE assigns logical devices to 
peripheral devises attached t o t h e 
CompuLer. and sets the "omun~cationl 
prot..oland 
speed of aperlphecaldevrce. 


"ore that the phyrlcal devices avnllable 
can diffec fiom sysren to syatea. consult 
yovrhardwaremanufacturer's dosumentatlon 
for v a l r d devloe names. 
A" exp1.n.ri.n 
o£ 


the val,d device optrona follows: 


DBVlCB OptionB: 


option 
Explanarlo" 


X a 
sets Lhe device Lo the XON/XOPP 
co"""""L.nrions 
protocol. 


R0xC.i 
Tndicates no probocol; the 
computer sends data t o the 
aeYlFe whether or not the 
d e v ~ c e 1s ready to reselve lt. 


baud-rare 
Is m e speed of the devise. 
T h e s y s t e m a c c e p t s t h e 
following baud rates: 


EXslp1es: 


A>DBYICE E m : - L P T , C R T 


A h S L g n s the system Eonsole ourput 
1CONOUT:I ro ?he printer (LPT:) and the 
aoreen ICRT:) . 


I\..1r;n. 
rnc a,xr,r.cy 
Lorlsal Ln2.r 
ocv.cr. 


A U X l h . 
to rnr pr,r,ca, 
dcvlce TR"2: 


. s r n q 
PCOCOCOI XON X ~ T P . dntl qers r r c 


r r r n s n ~ s s ~ o n 
r a r e f , c 
r l c nczlcr a t 9 6 C C . 


A>DBVICB LST:-IRLL 


~ ~ s c o n n e c ~ a 
the h s r output logma1 d e n s e 


ILST:) _ 


ArDBVlCB LPT IXO11.96001 


s e t s *he XON/XOPP pcotoso1 for t h e 
physlsa1 d e v ~ c e LPT: and sets t h e 
t i a n a m ~ s s l o n speed a t 9600. 
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CP/M ~ l u e 
command Summary 


DEVICE (continued) 


Purpose: 


DEVICE dlspiays or 
sees the current 


console screen s,re. 


BIa.p1ca: 


A>DBYICB COLISOLS lPUiBl 


Displays the current console page Width in 
columns and length I" Ilnes. 


Serb the screen alae to 40 columns and I6 
lines. 


DiR 
DIE d: 
DIR filespec 


DIR d: options 
OIR fllespes. ... filespec optlonr 


The DIR and DlRS commands display the 
names of Llles cataloged In the dlrestory 
of an on-llne dlst. 
DIR llats the names 


of files In the cvrrent user number that 
have the Dzresrory (DIR) atrrlbure. DIRS 
lists the names of flier 1" the CurrenL 
directory t h a t nave the system ISYSI 
nttrlbute. 
DIR and DIRS accept Lhe ' 
and 
? "lldsards 1" *he file spesrfisatlon. 


The DIE command with oprlons dlsplays the 
name5 of flies and the characterlsrlcs 
.ssO.i.ted 
W L t h the files. 


DIR and OIRS are built-ln uklllkler. DIR 
v l r h opt,ona La a transient U t L l l t Y and 
msr be loaded into memory fro. the dlS*. 


.L,Dlsl 8: 


OLsplaya a l l DIR frles I n user 0 on drive 


21,018 C:ZIPPX.DIT 


Displays the name ZIPPY.DAT If the file is 
I" user 2 on drive C. 
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DIR (continued) 


Displays a l l OIR f i l e s i n user I on drive 
whose filename begins with the letter X. 
and r h o a c three-charaster f ~ l e r y p e 
sontalna the first character c and last 
ShacaCLec D. 


ArDIRS 


Displays all flleli Lor user 0 on drive I 
that have the system 16YSI attribute. 


~ l s p l a y s 
a11 SYS f i l e s with filetype COM 


on drive A i n usel 0. 
A oo"""an.3 
["OM) 


f i l e in user o vlrn the eyatem a t t r ~ b u r e 
can be acceaaed fro," any user number on 
that drive. and from any drive i n the 
Seal& 
Shaln [see SETDEW). 


firpose: 


T h e DIR connand with optlons l a an 
enhanced veralon of the DIR bulir-in 
oommand and displays youl: f i l e s in a 
Y a I i e t y of ways. 
DIR can aearsh for flies 


on any or a l l drives, Lor any ox d l user 
numbers. Oneor two letters 1s sufficient 
to Identify an oprlon. 
YO" need not type 


the r i g h t square bracket. 


am 


Displays the user-definable frle 
attributes. 


ram 


Displays date and rime atamp. 
Of 


fllell. 


ora 


f is playa only € i l e a that have the 
DIE atkzlbute. 
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DIR (continued) 


option 
~ u n s r l o n 


DlllM.4 


D i . p l . y s 
f i l e s on t h e d r i v e 


specified by d. 


BIcmn 


Dlaplays f l l e s that DO NOT MATCH 
the files spesrfled In the command 
l i n e . 


rE 


Sends an i n i t i a l form feed to the 
Pclnrer device i f the prrntar ha. 
been activated by CTAL-P. 


m u 


m 
- 
n 


Displays n l i n e s o f printer output 
before inserting a table hesdlng. 
n La s number between 5 and 65536. 


"Xs-E 


Dieplays the naaea of diiveli and 
user numbers DIR rs searching. 


llPIOB 


continuou.iy s c i o l l s info..aflon 
by 


on the screen. 


llDSORT 


~ l a p l a y m f i l e s i n the order i t 
finds them on the die*. 


D 


Dimplay. only the €Ilea that h.ve 
the Re.d/Only 
attribute. 


rn 


Display. 
Only the t i l e s that or. 


set t o Readmrlte. 


SIZE 


Oi.pl.y. 
the tilemano end .,re 
i n 


kilobytes 11024 bytes). 


DIR (continued) 


SlIS 


isp play^ only the files that have 
the SYS srtrlbute. 


0 s - r n 


Displays a11 flies in all user 
n u m b e r a f o r t h e d e f a u l t or 
specified drive. 


USER." 


Dlsplsyli the files in the uaer 
number specified by n. 


Um-l0,1,...,151 


Di.pl.y. 
files under the user 


numbers specified. 


?aa.p1es: 


A > D I I C, 1-1 


Displays full s e t of characlariatlcs for 
all fllea in ueer 0 on drive C. 


W D l R C i IDImI 


Liars t h e files on drive c and their 
dates. 


A>DIP Di lR*,SYSI 


DiBplayS .I1 
flies I" use. 
0 on drive D 


with ~ e a d m r i t e and system attributes. 


3lrDIR I D - U . 
OIIVEI-I 


Displays a11 the files in all user numbers 
10-15) 
~n all on-line drlvea. 


86>01R IEK-El 
..DIT 


~ 1 s t ~ 
a11 the riles on drive B ~n ueer 6 


t h a t do nor have a flierype of o m . 


3B,DIP 151181 '.PLl 
+.n* *.- 


Displays all *he f l l e s of type PLI. COM. 
and ISM in user 3 on drive B In arze 
d~eplay format. 


ce/n plus command svnnary 
- 


DIR (continued) 
- 


A,DIR 
IDES-- 
O-P--1 
-IY.BOB 


DIR dL8pl.y. 
t h e fllename TESTPILE.BOB If 


i t is found on any drive 
1" any user 


number. 
- 


DIE 1 1 ~ 1 9 
each aeawwrite file t h a t 
- 


reside. 
on Drive D. 
" l t h Its sire in 


krlobytea. 
Note rhar D: Is equivalent to 


Di'.'. 


DUMP 


synt.., 


DUMP filespec 


Purpose, 


DUMP displays the contents of a L ~ l e 
~n 


hexadecimal and ASCII format. 
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ED 
ED input-filespec 
so input-lileepec (d: output-fileapecl 


charaster s ~ l e 
editoz. 
TO redirect or 
rename the new veraion Of the file specify 
t h e destination d r r v e or destlnatlon 


nr 


append n lines from original file co 
memory buffer 


O I 


append file ""tll buffer is one half 
full 


*A 


append file until buffer is full l o r 
end of file) 


B, -B 


move CP to the beqlnning 181 
Or 


bottom 1-81 of buffer 


"C, -ne 


move CP n characters forward ICI or 
bask I-Cl 
through bYffel 


"D, -nD 


delete n characters before I-D) or 
from ID) the CP 


save new file and return LO CP/M 
Plus 


.string-l 


find charactel srring 
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ED (continued) 


m, -m 


delete (kill) n llnes from the CP 


DL. -DL, 
Or. 


move CP n llnea 


-"ds 


execute commands n times 


n. -n 


move CP n llnes and display that 
line 


move ro ilne n 


:m-d 


execute command through line n 


Ll.t.in.+ 


extended Flnd string 


return to original file 


"P, -nP 


move CP 23 lines forward and display 
23 lines at conaole 


a 
abandon new file, return ro CP/M 
PIUS 


R-* 


reed ~$SSSSSS.LIB tile into buffer 


M1te.pec-z 


Iead filespec into buffer 


Sdelete-.t.iw-.in~e~t-ttti"g 


aubstirure strlng 


nr, -nv, OT 


type n lines 


0 , -0 


uppercase rranslarl.3" 


V, -v 


line nuloberlng on/off 


0" 


dlsplay Free buffer space 


ED (continued) 


Cornand 
Act ,on 


nw 


vrlle n lines to new file 


o* 


vrlte ""ti, 
bvffer l a half empty 


nl( 


w r i t e or a p p e n d n l i n e s to 
X l l l E S I S . L I B 


nifile.pecAz 


vriLe n lines to flleapeo; append If 
p'evious 
xcomand applied to same 
file 


0.-z 


delete f i l e X I I $ I I I I . I ~ I B 


Oxfile-^l 


delete f~lespec 


nz 


Wait n seconds 


sore: CP polnrs to the current charactex 
telw referenced in the edit buffer. 
use 


CTRL-z 
to separate nvirlple commands on 
the sane line. Your screen displays " Z . 


ERASE 


[CONFIRnl option informs the system to 
prompr for vellficatlon before erasing 
each rile t h a t matches the filespec. 
CONFlM can be abbreviated to C. 


zx..p,ellz 


A r E m E =.PAS 


Removes =he file X.PIS from the disk in 
drive A. 


ERISB '.PUN 
IY/NI 
7 1 


AIL files with me filetype PRN are 
removed from =he dlat in drive A. 


&.sh file on arlve I with a filename that 
begzna with MY 
is displayed with a 


westion mar* for con€irnation. wps Y to 
erase the file displayed. N to keep the 
file. 


li>m 
B,... 


ERASE s:... 
(Y/N) ?I 


111 files on drive B ace removed from the 
disk. 


GENCOM 


GWCO(( CO(tfil..p~c Psx-t*l..pn.. 
.RSx-ti111po 


[ IMADER 1 SCB=loffTet,ualue) 11 


CENCOn RSX-filespec ... RsX-filespec 


1 [NULL I SCB-(offaet,value) 11 


CBNCOM filename 
CENCDH filename lSCB-lO€fBet.ualue)1 


me oe~con comma 
~ s x 
files to a 


COM file, or create. . 
d u m y "0" file 


mnralnlng only RSXS. 
~t can also restore 


i( previously OENCOIled file to the original 
CO( flle withour the header and R6Xa, add 
or replam RSX5 in already OBNCOMed files, 
and attach header records to COM flies 
wlthour RSXS. 


optlo" 
Function 


-En 


s e t s a flag to keep the program 
loader .ot,ve. 


m 


TndLCaLeL that only RSX flles are 
s p e c l f l e d . 
OENCOH creates a dumy 


COM flle for the RSI files. 
The 


output CO" 
filename 2s taken from 


the filename of the first asn- 
filespec. 


bCB-lO€€.ek.".l"e, 


Sets the system control m o s t from 
the program by v s m g the hex values 
specifled by (of€sef.value). 


Generates a new con file MYPROC.COH vltn 
attached RSX's PROGl and PROC2. 


GENCOM (continued) 


A>GBICO* P m I P S a 2 LWULLI 


Creakes a COH file PROCl.COM With RSX'S 
PROOl and PROOZ. 


*>GBnUI KZPDDC 


GENCOM takes MYPROC.COII. 
strlps off the 


header and deletes a11 attached Rsx's to 
resko.e 
it to its orlglnal con format. 


owcom laoka at the alroady-OBW(ed file 
MYPROC.COM 
to see 
I f PROC1.RSX 
and 
PRODZ.BSl are already attached R5X files 
In the module. 
If elkher one ra already 


GENCOM replaces ~t w ~ t h 
the new 


RSX module. Otherwise, GENCOMappends the 
apcclfled R6X files 
Lhe COM €lie. 


GET 


syntax: 


am ICONIIOLE 
INPUT PROM] PILE tilespec {optionst 


GET (CONSOLE INPUT PEON/ CONSOLE 


Rlrp3.e: 


OET dlresta *he system to take console 
input from a f ~ l e 
for the next system 


command or user program enlered at the 
console. 


aptlo" 
sunction 


BCBO 
s p e c i f i e s that input i s echoed 
t o the console. 
=his i s the 


default optLon. 


BO BCsO 
Specifies that f i l e input la not 
echoed to the console. 
The 


program output and the system 
prompt* a c e nor affected by 
t h ~ s 
o p t i o n and are still 


echoed Lo the console. 
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GET (continued) 


to the console roc console LnpuL. 


*>GET PI= XIR? LSYS-I 


~ m r n e d ~ a t e l y 
d ~ r e s t s the sysreln LO get 


Lubsequenr console input from file XINZ 
because I t Includes the SYSTEM optlon. 
me system reverts back to the conrole for 
console Input *hen It reaches the end of 
file ~n XINZ. 
or XINZ can r e d i r e c t the 


system back ro the sonsole If It contains 
a GET CONSOLE command. 


Tells *he system to get oonsole input from 
Me "onsole. ThlS command can be used I" 
a flle (previously specified in a GET PILE 
oommand,, whish 1s already being read by 
Me system for console Input. 
It is used 


to redirect the oonsole ,"put back to the 
console before me end of L I I ~ 
is reached. 
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HELP 


BELP 
HELP ropic 
HELP toplo subtopic 
HELP topi= INOPACEI 
HELP roplc SY~LOPICI...SY~~OP~CB 


BBLP d l s p l a y s a l i ~ t 
of to#iss 
and 


p'ovides 
summarlred Infornarlon for CP/M 


Plus comnands. 


Typing HELD topic dlsplaya mformarlon 
about t h a t t o p i c . 
wping Her.? 
ropic 


sYbtOpis dlsplaya ~nformatlon about that 
SubtopLC. 


one or two letters 1s enough to identify 
t h e toplca. 
hfter HELP d i s p l a y s 


lnforlolltion for your rop,s, 
It dlsplnys 


the special prompt ner.PI on your screen. 
Followed by a list of subfopiss. 
. 
mter ? to display llsr of main top,ca. 


Enter a perlod and s u b t o p ~ c name to 
asseas subtopica. 
. 
Enter . 
period to rediaplay what you 


lust read. 
. 
Press RETURN to retutn to the CP/M Plua 
system prompt. 
. 
lNDPlOBl opeion dlsables =he 24 llnea 
per page console display. 
. 
Press any key to exlt a display and 
return Lo the HELP, prompt. 


A>-P 
I,BBLP Dim 
I'BBLP 
DIR OAIrnLII 


A>BBLP>.OPTIO(IS 
HELP,SET 
HELP,BR P-RD 
H E L P > _ P ~ O B D 
HELP,. 
HELP,rRET) 


syntax, 


HEXCOM filename 


Example: 


A>BBICOI B:PPODPU 


Oeneratea a cornnand file PR0CRIUI.COM Fro. 
Lhe LnPUt hex frle P R O C M . H E I on d r l v e 
B:. 


CP/M Plus Cornand summary 


INlTDIR 


EXa.F.1e: 


a>rx=mrr, c : 


lNlTDIR HILL ACTITATE 
TIME STAMPS FOR 


SPECZFIED DRIVE. 
DO you want to re-format 


the directory C: I Y / N ) 7 1 


CP/M Plue Command Summazy 


LIB 


S Y n r Y I 


LIB fllespes 
LrB fLleSpeC Iz$zt:]-fLlespec 
<modifier> 


j.€llespes<.odlfler> ... j 


Purpse, 


I, 
ilbrary 1s a file that c o n t a ~ n a a 


mllecrion of ablest modules. mse the LIB 
u t l l l r y to create llbrariea, and to 
w e n d , rephoe, select, or delere modules 
from an e x i s t i n g library. 
Use LIB t o 


obraln lnforlaation about the contents Of 
library file.. 


LIB creates and ma.ntams 
library files 


t h a t c o n t a i n o b j e c t modules 
M1010s0ffQ RBL file format. These mdulca 
a r e p r o d v o s d 
b y 
r h e 
o i g i r a l 


Researche relocarable macro-aaaemblei 
program. 
WAC", 
or any orher language 


translator t h a t pcoducea modules ~n 
nioroBofr REL file format. 


YOU can use LINK-80- to link t h e oblect 
mdules contained in a library to Ochel: 
object flles. 
LINK-80 autonaLisally 


eelccts from the library only those 
lnodulcl needed by the program being 
linked, and then forms an executable file 
with a filetype of COM. 


Oprlon 
runcrlon 


I 
The INDEX Option creates 
an Indexed Ilbrary file of 
t y p e I R L . 
L I U R - 8 0 


s.a..hes 
faster on Indexed 


l i b r a i i e s t h a n o n 
"onindexed libraries. 


8 
tmDuLe oprlon a,splaya 


module names. 


P 
he 
P U B L I C S o p r l o n 


dillplays module names and 
the public varllldlell LO. 
the new library file. 


D 
The DUMP option displays 
the Eontents of o b l e c t 
M d v l e s in lSClI form. 


LIB (continued) 


"odxfler 
Meaning 


mmre 
<mMula=> 


Replac. 
'.od"le-filename.RELI 
If d u l e name and ti1ena.e 
are 


the same, y o u can use the 
following .horthand: 


<file"...> 


seleer 
I ~ O ~ F I R S T 
-- 
=ST. m... 
mod^) 


Exwles: 


I)>LIB TBSTIIPI 


DiSplayL all modules and publics 2" 
TESTI. REL. 


a>=re ~ T S I P I - P I L B I , F I L B ~ 


Creates TESTS.REL 
from PILE1.RBL and 


FILE2.REL and d l s p l a y s all nodules and 
P Y b l l C 5 I n TESTS.REL. 


Creates a llblary flle TEST.REL flon 
nodules in two source f i l e s . 
TESTI.REL 


sontrlbures MOD1 and MOD,. 
LIB e x t r a c t s 


nodules ~ 1 . 
~ 
4 
, 
and all the modules 


la2ated between thelo, as well as module C6 
from TESTZ.BEL. 


li>LIB IILE*-FILB3<*ODI-r 


Creates PILE2.REL f r o a P I L E 3 , R E L , omitting 
llODA, YhlCh is a module ~n Flrel.nEL. 


A>LIB PILB6=PILBS<MDI=FILBBLBBB3LL 


C r e a t e s PILB6.REL from FILES.RHL: 
FILEB.REL repiaces MODA. 


LIB (continued) 


Module THISNUIB i s in PILES.RE6. When LIB 
cleates PILB6.REL froloPILES.REL, the file 
THISNANE.REL replaoes the almllarly named 
module THISNAME. 


A>LIB ~ 
I 
I 
a 
~ 
~ 
I 
~ 
- 
~ 
: 
~ 
I 
~ 
~ 
~ 
P 
~ 
, 
~ 
~ 
~ 
, 


SBIRCB-DISPLW 


Creates PILB1.IRL on drive A from the 
Selested nodales PLOTS, FIND. and modules 
SEARCH through the module DISPLAY, in 
FILEZ.X_BL on drlve 8 . 


Urn. 
LINK OpIlon .rlisn.. 
r o control 


ur.3t.on pra..r.c.. 
'lnr 
oprron. to.10" 


tn. 
$ I . . 
sp.c~tls.r~on. 
and .r. 
mns.0m.d 


"Ilhl" .q.Iar. 
bI*S..L.. 
Mditlpl. 
.l*CCh.. 


drs "plrar.d 
by sD.DOs. 


wt.on 
Punctlon 


A 
Addltl.".l 
u m r y : reduces buttar 


.WS# aria wr1tc. reworary data to 
dl.*. 


s 
sros ,Ink 
1" 
banked cp/n PLUS 


system. 
dllgnll data segment on 


Page boundary. 
Puts lcngM of 


c d e ssvment ~n header. 
Defaults 


CO SPR flletype. 


D N l M mta or1g.n; 
sets mewry orlgln fox 


commn and dots area. 


(LI 
Go: set srsrt oddre.. 
to label n. 


Ulhhh I.oad: change *etau,t 
L0.l 
.ldr.s. 


of m u l e to hhhh. oerault oloos. 


lhhM Memory stre; DDflno *ice u m r y 


rcqulrements tor HP/II" Wdulee. 


m 
NO i ~ s t l n g ot symbol raole at 
SrnSOlC. 


sn 
no symbol table fll.. 


CP/M Plus Command Summarl 


LINK (continued) 


a t p u t con commama rile. Default. 


Output PRL page ielocatable file 
for C X C C U r l D n under HP/M i n 
lelocatable Ilegment. 


output RSP resident system process 
file for execution under MP/". 


output SPR system page relocatable 
file for execurlon under MP/". 


program origin; ohanges default 
program Origin address to hhhh. 
Default is OlOOH. 


LiSkB symbols with leading quesrlon 
mark. 


Search preceding file as a Ilbrary. 


Destination Of sonaole.ess.ges. 
d 


=an be X 
(consolel, I IprlnLerI, 


or I 1rero output). Default 1s X. 


Saul-ce of intermediate files, d is 
disk drive A-P. Default la current 
drive. 


$Id 
s0nr.e 
Of library files, d re dlst 


drive A-P. 
Default is ourrent 


drive. 


PW 
Destination of object file; d can 
be z or disk dxlve A-P. 
Default 


1s to same drive a* L x s r flie I" 
the LINK-80 command. 


$ad 
Destination of symbol file: 6 can 
be Y or z or disk drive A-p. 
Default is to same d r w e as flrsr 
file in LINK-60 command. 


LINK (continued) 


LINK-80 on d r i v e A 
u-em 
os i n p u t 


IP(FTLE.rn on d.i". 
B and produo.. 
Ule 


executable Mchino code file IP(FILE.COM on 
drive 8. 
The [NRI 
optlon specifies no 


symbol table file. 


*,LL.K 
.l,.2..3 


LINK-80 oombines the separately oomplled 
€ilea 11. m2. and 13. resolves rhelr 
external references, and produses rhs 
executable machins cmc file m1.con. 


ArL- 
-,.2,11 


LINK-I0 mmblnos tho separately compiled 
file. 
.I, 
m2, 
and . 
3 
and produces the 


executable namine cod. file .."OM. 


),LIP: 
mrm.rrm5[.1 


me Csl option reus rr~n-so t o search 
PILES as a Ilbrary. 
LINK-80 Combines 


KIPILB.ReLrirhrh.referenced smroutin.. 
contained in PIlrE5.Ra on the default 
drive A and plodus.. 
,"YPIPILB.COM on alive 


CP/M Plus Cornand Summary 


MAC 


syntari 


MAC fL1ena.e 
(80~r,~"a) 


MAC", the CP/M Plus macro assembler, reads 
assembly language statements from. 
File 


of type asn, assembles the staremenrs, and 
oroducer three outout Llles With the lnovt 


optlo" 
Punstlon 


A 
source drive for As" file (A-0, 


B 
destlndlrlon drlve for HEX flle 
(A-0, 
Zl 


L 
source drive for macrollbrary 
LIB files called by me mcrre 
srarement. 


P 
destlnatlon d r ~ v e for PRN file 
IA-0. 
X , P, Zl 


s 
desrlnarlon drive for SYH file 


+L 
11sta inpur lines read from 
..srolib.ary 
LIB ellea 


-L 
suppresses llstinp ldefavlrl 


+" 
Ilsca all macro lines becavae 
they a r e processed during 
assembly 


MAC (continued) 


option 
F""Ctl.3" 


-M 
svppreases all macro 1lnea 
because they are read durlng 
assembly 


an 
115ts only her generated by 
macro expansions 


+a 
lists a l l Lmlir. symbols in the 
llynbol h s r 


Q 
Suppresses all LOCAL symbols ~n 
the symbol list (default) 


+S 
appends symbol file to prrnr 
file 


-S 
suppresses srearlon of symbol 
file 


+1 
produces a pass 1 liatlng for 
macro debugging in PUN flle 


-1 
suppress lisling on pass I 
l d ~ f a u l t l 


Xxa.p1es: 


I,- 
SUP- 


MAC assembles the file SIMPLE.lSM. 


I\>- 
W L B SPB AA BB % -" 


1n t h l a example, the option list direst. 
the PRN flle to drive 88, obtains the ISM 
file from drive A,, 
drresrs the "EX file 


todllve B:, the SYn flle to the console. 
and suppresses all macco lines during 
assembly. 


CP/M PIUS connand Sonnary 


PATCH 


Rlrwse: 


=he PITCK =onnand displays or installa 
mrch number n to me CP/H ~ l u a 
system or 


eonnand fllea. me patch number n muat be 
between I and 32 inclusive. 


h w l e l 


I>PlrnB 8- 
2 


Patches the SHOW.COM system file with 
patch number 2. 


CP/M Plus Command Summary 


PIP 


synr..: 


Destination = source 


PIP 
PIP d: l C n l ~ - f l l e % p ~ s ~ o y n o n r 
PLP tr,..prs, 
C" 
ifllcspcc o p r l 0 n r . l . ... 
PIP t.l..P.C 
I.",, 
d.YIC..LI,..>ec 
OPllO"., 
d.VIC. 


COPY A PILE PROM ONE DISK TO &NOTHER 


A>PIP b:'aldrafr_t;.t 
ArPlP b:draft.tl* 
a: 


BJ,PIP lyfLle.dak-ll~IC91 
19,PIP B:Icll=qf'le.dat 


COPY A PILE AND RENAME IT 


15,PIP n&raft.txr-oldraft.t;.t 
C81PIP brncrdraft.txt=a:old~~ftrt;.t 


COPY MULTIPLE ZILBS 


li>PlP b:-dr.ft.* 
A>PIP b 
: 
. 
. 
. 
' 


BIPlP b:-C:.... 
C>PIP .:...-l.rl 
B>PIP a:(g31=~:*.* 


CP/I( Plus Cornand Summary 


PIP (continued) 


COMBINE MVLTIP1.E PILES 


A,PIP blner.dat-tilel.dat,fiI12.ddt 


COPY, RENANLIIE AND PLACE IN USER I 
pip ndrafr.t.t1411aldrafr.txt 


COPY. RENAME AND GET PROM USER I 


li>PIP ndr.ft.trt-oldnfr.t.r,gl, 


PIP options: 


option 
PYnCtion 


A 
~ r s h ~ v e . 
copy only filer that 


have been changed s i n c e the 
lest copy. 


C 
Conflr.. 
PIP PrOmprE for 


conflmmatlon before each file 
SOP,'. 


on 
oeiere any chaiacters past 
column n. 


E 
~ c h o 
transfer to conaole. 


r 
F i l t e r form-feeds from source 
data. 


Gn 
Ger from or go to user n. 


B 
Tesr foe v a l i d "ex format. 


I 
rgnore :00 Hex data records and 
test for valid Hex rornat. 


L 
T r a n e l a t e u p p e r c a r e to 
lowercase. 


II 
Number ovtpvt lines 


o 
o b j e c t rile transfer. 
" z 


ignored. 


RI 
Set page length t o n . 
(Default 


"-601. 


PIP (continued) 


PIP option.: 


option 


0s-z 


Function 


Quit copying from source a t 
strzng s. 
Read files that have been set 
to SYSrem. 


s t a r t c o p y ~ n g from the source 
at the string a. 


expand tabs to n spaces. 


T r a n s l a t e l o r e l c a s e to 
uppercase. 


verify that d a t a has been 
written correctly. 


#rite ovcc ~ e a d / o n l y filra 
"IthoYt console query. 


ear0 the ~ " i t ~ 
bit. 


111 options except C. ~ n , 
K, 0 . R, V, and 


w force an MCII file transfer. character 
by chacaotez, terminated by r A Z . 


CP/M Plus Command summark 


PUT 


PUT W l t h the SYSTUl option dlrects all 
Subsequent sonsoie/prlnler output to the 
Dpesrfled file. 
Thrs optlo" cer.,natea 


when you enrec the PUT CONSOLB or PUT 
PRINTER Command. 


BCBO 
Speolfles thatovtpvtiseshoed 
LO the console. Thrs is the 
default optlo" "hen you direst 
sonsole ovrpvr to . 
file. 


m LeeD 
s p e o ~ f ~ e a 
t h a t file output 1s 


not echoed to the console. NO 
ECSO la the default for the 
PUT PRINTER sonunand. 


P 
I 
spesxrxes fllrerzng ofsonrrol 
characters. which means that 
control c h a r a s t e r s a r e 
translated to p r i n t a b l e 
characters. 
ror example. an 


escape character is translated 
r0 
I. 


m F 
I 
L 
~ 
M e a n s t h a t POT doe* nor 
translate control characters. 
This is the default option. 


PUT (continued) 


m= options: 


BXq1es: 


A>mT COL160LB -PUT 
TO 8ILB XDITr 1-1 


Dlrecrs sonaole output to flle XOUT With 
the ourput echoed to the console. 


Directs the prlnrer ovtpur of program 
MYPROG to flle XOUT. 
The output Is not 


echoed to the prlnrer. 


A>- 
PRI- 
rn m PILB -2 


tmo.snrsc1 


Directs all printer output to flle XOUT2 
as well am 
to the prlnrer (with ECHO 


optionl, and the PUT Is in effect until 
you enter a PUT PRlWTER DVTPUT TO PRINTER 
couuna. 


&>POT W ~ L . m- 
m omsore 


Dlrests console output b a s k to the 
console. 


CP/M Plus Connand Summary 


RENAME 


syntax: 


RENME 
RENME nex-fllespes=old-fl1esppp 


lets YOU change the name of a file 


I" Lhe directory of a d l s k . 
To change 


Several filenames m one cornand use the ' 
or 7w1ldCards In tbe file specif~sakiona. 
You can abbreviate t h e RENME command to 
REN. 
RBN prompls you tor ~ n p u t . 


The eysrem prompts for the following 
€LleEpecs: 


Enter New Name:X.PIUI 
Enter Old NanelI.PIUI 
Y 
.PRN.X 
.PRN 


Flle X.PRN is renamed to Y.PRN on drive A. 


I:F%IWTS.IIBV=PRI"CE.WW1 


The flle PRINCE.NBW on drive li changes Lo 
PRINTS.NBW on d r l v e A . 


a,- 
S . . m - A * . W 


me above command renames a l l the files 
matching A'.TEl 
to files vlrn filenames 


S'.TEI. 


RENAME (continued) 


The file OLDLIST changes to NEWLIST on 
d r i v e 8. 
Beoavse the second d r i v e 


specifier. B:, 
is ~mplred by the f l r r r 


one, it I. 
unnecearary m thLS example. 


me cornma line above has *he sane 


CP/M Plus Command Summary 


*tax% 


-c 
filespec Iopt1ons) 


Purpo.ei 


Mac, a relosatable macro a.a*.bler, 
assembles A S I frles into REL fllea that 
you can lint to oreate call files. 


RIUC Options specify the destination of 
the output file*. 
~ e p l a o e d "irn the 


destination drlvc letter for the output 
files. 


ouc opt*- 
(a-output option p a r u t c r l : 


R4 
drive for REL file ,A-0. 
Z ) 


Bd 
drive for Sm file la-0. X, P, I) 


W 
drive for PRN flle I&-0, x, P, z) 


h-3 
epccifies drive A-0 


X 
means ovtput to the console 
P 
means output to the p..n*er 
z 
means .ero outpur 


Consolr. p l l s t l c 3ymb01 flle .TEST.SYM) 
on drive B and put. the rc1ocarao.e oolrct 
I l l * (TEST.RhL, on d r r v e 8. 


CP/M Plus Command Summary 


SAVE 


syntax: 


SAVE 


SAVE copiea the contents of memory to a 
file. To use SIYE, flrac isrue the SAYE 
cornand, then run your programwhish reads 
a file into memory. YOU 
program exits to 
the 5 1 ) ~ ~ 
utility vhioh prompts you for a 


filespec to which i r oopies the oontenta 
of memory, and the beginning and ending 
address of the neloory to be SAVEd. 


r..91*: 


*>mYB 


RStlYates the SAM utility. Now enter th* 
name of the program which loads a file 
Into mcmry. 


A>blD d u p . c a 


Next, erecute the program. 


*go 
men the program exits, S A W Intercepts 
the return to tne sysre. 
and p1onprrr UIe 


user fox the LII.SP.3" 
and the bounds o t 


.e.ol.y 
to be SIVEd. 


SAVE Yer 1.0 


SAVE (continued) 


E n t e r 
f i - l e [ p r e s s R E T U R N t o 


exit) :d-2.com 


I€ file DUMPI.C~M exists a~ready, the 
system asks, 


Delete dunp2,com? x 


Then the syeten aaks for the bounds of 
memory to be saved: 


Beginning he. 
oddreas, 100 


Ending hex addzesa: 400 


T h e Eontents of memory from ~ O O H 
IHexndecimall to 400" l a copled to file 
DUIIP2.COM. 


SET 


SET [options1 
SET d: [opr~onsl 
SET filespec Ioptionsl 
SET loptlon - laodi€ierl 
SET fileepes [option - modifier1 


EX.q1esi 


SET Disk Label operations: 


li>SWr ItW#E-DIBK1001 


~ 
~ 
b 
~ 
l 
s 
the disk on the default drive as 


DIsr100. 


A r m IPIBBIOBPSErnI 


Assigns SECRET to the disk label 


SET (continued) 


Pllb(l.oxd ROfection *o6lfiers: 


W i f i e r 
Protection 


REm 
The password IS requlre.3 foz 
::::::: ;rc::"x:g 


W T B 
The Password 2s required for 
wrltmg, deleting or renanlng 
the file. 
You do nor need a 


PabPWocd LO read the file. 


DBrSTB 
The password l a only r e q u ~ r ~ d 
Lor deleting or renaming the 
f i l e . 
You do n o t need a 


PaSSXOTd LO read or modify the 
f i l e . 


mccw 
Nopassword e x i s t s for the f i l e . 
:dd,:Z;." 
:;"::,a&:: 


the pasa*ord. 


SET P i l e lttribYte *tlons: 


optlo" 
Function 


so 
sets t h e f i l e attribute to 
Read/Only. 


rn 
sets the f i l e artrrbvte to 
Rendnrlte. 


SYS 
set* the tile attcibute t o 
SYS. 


DIR 
Sees the file attribute to 
DIR. 


~ 
X 
M 
- 
0 
b a n s that the f i l e has nor 
been baoked up la~chived). 


AXBIY..ON 
means that t h e f i l e has 
been backed up larshlved) . 
Tbe Archive a t t r i b u t e can 
be turned on by SET or by 
PIP "hen copying a group 
Of fllea vlth the PIP I A I 
O p t i o n . 
SHOW and DIR 


d i . p l . y 
t h e l r s h l v e 


optlo". 


Fl-UJJon 
Turns on or of€ me user- 
definable f i l e attrlbure 
PI. 


w2.ONIOTr 
Turns on or off the user- 
definable r i l e attribute 
P2. 


SET (continued) 


SET ~ i i e 
~ttribute options: 


option 
FYnctLon 


1141011 
Turns on or off the user- 
definable rile attribute 
P 3 . 


P I - ~ O ~ 
~ " r n s on or off the uaer- 
d e f ~ n a b l e file attribute 
F1. 


Turns on pasawor.3 protectlo" tor a l l the 
files on rhs die*. 
YOU must rurn on 


password pl.ote.rion before you can ..sign 
paaaword, to f l i e s . 


r,sm [P-I 


Disables paasword protection for the fil.. 
on your dlS!,. 


r s s r mrrs.mx [ P m w - n r r L l 


MYFTL 
the paasword asalgned to flle 


"YFILE.TEX. 


A~~~~~~ 
the passrocd SECRET to all the TB( 


files on 
B. 
zach TBX file is given 
. 
W R I T 6 p r o r e s t node to prevent 


unaurhorlred editmg. 


sm Default pa.. rord operation: 


*>SET IDWI&T-P~SS.OI~~ 


rnsrrYcts the system t o use a default 
psrsrord if you do not enter a password 
for . 
pasarord-protected file. 


SET (continued) 


SET d l , lCRUTB-ON 
OTP, 
:::I::; ;E:?;::: 
:;:I 


ma above SBT comanda a l l a you to kaep a 
record of the tzne and date o f f i l e 
creation and update, or of rhs lase access 
and update of yovr f i l e s . 


I K C B S S Q I 
Tarnson ACCBSStins stamps 
on the disk in me default 
or s p e c i f r e d 4 r i v c . 
XCESS and C-TE 
options 
are mutually e.clu.i"e; 
Onlv one can be in effect 


SET (continued) 


mw1ei 


A r m 8: [.Dl 


Sets d r i v e B to Read/OnlY. 


SETDIP aI1Drs the user to dieplay or 
define up t o four drives for the program 
search order, the drive for temporary 
fllea, and the riletype search order. m e 
S-F 
definirions sffscr only the landing 


of programs and/or execution of SUBMIT 
(SUB) file.. 
SETDBF turns on/off the 


system Dlaplay and Console Page modes. 
men on, the aysrern dleplays the losatlon 
and name of programs loaded ox 
SUBmLt 


flies executed, and stops after displaying 
one full Eonsole screen of inlornation. 


r>s.mn l~mmararsx~ 


E-zts disk drive C as the drive to be used 
for temporacy €ilea. 


ells the system to search for a program 
on drive C, then, if not found, search For 
it on the default drive. 


rn~truors the system to search fox a sue 
flle ko execute. 
If no SUB file is found. 


search for a COM file. 


A>-BP 
IDlSPIIYI 


Turns on *he system display mode. 
The 


system now displays the name and losarion 
Of pro r a m 8 loaded or submit files 
..... t.2. 


li>SBmBP 1110 DISPLAY1 


Turns Off the system Dlsplay mode. 


CP/M P l u s Command Sumaiy 


SHOW 


P u r v e t 


The SHOW camand displays the following 
disk drive information: 
. 
access mcde and the amunt of free ars* 
space 
. 
dlak label 
. 
current uaer number 
. 
nu*r 
of riles for eaoh user number on 


the d i e * 
. 
number of free directory entries tor the 
dlst 


Er.qle.. 


1,880* 


* r s m ISP1C*I 


Instructs Lhe system to display access 
m e and amounr of apaoe left on logged-in 
drives. 


II>sm Bi 


Shows access node for d r i v e B and amount 
of space left on drive 8. 


1,5801 8: 1-BLI 


Dlsplays label lnfornation for drive B. 


C P B Plus Connand Jumary 


SHOW (continued) 


isp plays the current user number and 
Ule user* on drive A and the oorrespond~ng 
number of files alislgne.3 to them. 


A ~ B O * C: 1DlP.l 


isp plays the number of free directory 
entries on drive C. 


AS- 
I D U M I 


~ i s p l a y e the dcive characrerislios of 
drive A. 


CP/M Plus Command Summary 


SID 


synt.i: 


sro iplla-lileepeci (,sym-file~pe~l 


Am 


Enter assembly language Statements. 
8 is the s t a r t address. 


Catbid:!! 
to ..wry 
lOC.Li0" 
fro," SID. 
S 


is the called address; b is the 
value of the BC register pair? d is 
the value or the DE reglater parr. 


DhIl~lt.fl 


Dieplay memory in her and ASCII. H 


::a$ 
'."a",::.:"::df";:"P:,th'. 
Mn::f 


address. 


--file.pc 
I,.yl-filcspcl 


zoad progcam and symbol table for 
exeEYtlO". 


s.syl-file.pec 


Laad a S.llnbOl table file. 


F.,f,d 


Pill memory with constant value. 
o 


'8 
the start addross, f la the 


fznlsh address, and d is an 8-bit 
data ,re*. 


G(pI(.a(.bil 


Beg," 
Execution. p 
1s . 
s t a r t 


a d d r e s s : 
a 
is a 
t e m p o r a r y 


breakpoint. 


SID (continued) 


816 -Ms. 


Command 
Neaning 


Displays all sylobola With addresses 
in He.. 


m.a 


Displays hex, deoinal. and ASCll 
values of a where a is a symbolic 
expression. 


K 
. 
. 
b 


Cornputel, hex sun and differenoe of a 
and b where s and b are sylobolic 
eltples.ions. 


I 
- 
tail 


TnPYt CCP oomand line. 


~lsJl.fJ 


List 8080 mnemonic inatrucriona. a 
is the s t a r t address, and f is m e 
€L"iSh addre... 


*..b,d mve mmry BlOEt. s is the staxe 


address, h is the high address of 
the block, and d is the destination 
a t a c t address. 


P(P(.cJJ 


Plies point set, reset, and diaplay. 
P 1s a permanent breaNpoint address, 
c is initla1 value of paas counter. 


x€ile~pcI 
,a) 


Ilead Code/Sylobls. 
d is an offset 


to 
addreas. 


S"'J'sat 
Memory values. a is address 


d e l e value ia sent. and I is 16-bit 
-Id. 


rlnl.cJl 


T I a O e Program BXeCUtion. n Is the 
nunbcr of program steps, and c is 
the utility enrry address. 


*(wlinl,=Il 


T I ~ C ~ 
without call. w instructs PID 


"OL to trace Subroutines, n is the 
number of program steps, ."d 
c is 


the utility enrry addreas. 


SID (continued) 


la =he number of progmm seeps, c ir 
the utilily entry address, and W 
~ n s t r u c t e S I D not to L r a c C 
subroutines. 


V 


Display the value of the next 
available location in memory INEXTI, 
the next ~ocstlon after the largear 
flle read In IMSZBI, the current 
value of the Program counter (PC), 
and 
the address of the end-of- 


avallable memory IENDI. 


milespr,.,f 


Wrlte the contents o f a ContiguouS 
block of memory to filespec. 
f 1s 


rrnlsh address. 


XlfJl.1 


Exanine/.ltel 
CP" stare. f is flag 


b ~ r 
C, Z . I, e or I; r ra register 


A, 8. D, H. 5 01 P. 


-1cs: 


A>SID 


CP/M 
PIUS loads 6ID from drive A into 


memory. SID displays the I prompt "hen ir; 
1s ready to accept comands. 


A,B:SlD 
M m . - 


CP/M Plus loads SID and the plloqram f i l s 
SUIPLE.HEX into memory from drive 8. 


810 Utilities: 


SID (continued) 


=he RIST utlliry oreares a histagram lbar 
gmph) ~ h a i n g 
the relative frequency of 


ot code within selected program 


segments of the test program. 
The HlST 


u r r l i t y a l l o w s you ta monitor those 
seotlons of code t h a t execute most 
frequently. 


?he TRICB u t i l i t y obtains D bac*trsce of 
the lnarructiona rhar lea to a particular 
breakpoint address in a pc04cam under 
rest. you can collect the addresses of up 
to 256 i n s t r u s t ~ o n s between paas polnrs ~n 
U or T modes. 


SUBMIT 


The SUBMIT command lets you execute a 
group (batoh1 Of comands from a Sumit 
file la file with flletype of SUB). 


8W Cil..~ 


me SUB file can = o n t a i n t h e fouoring 
types of lines: 


.any 
valid CP/M elus =omand 
. 
any v a l i d CP/M Plue oomand w i t h SUBMIT 
parametere ($0-$91 
. 
any data inpur l i n e 


any program inpur lina with parameter- 
( $ 0 to $91 


'Ehe Eommand line cannot exoecd 135 
charact.~-s. 


DIR 
DIR ..BAK 
mc $1 I$$* 
PIP LST:-SI.?WIT$2 
$3 $51 


DIP. '.ASH 


CP/M PIUS Cornand Summary 


SUBMIT (continued) 


Bx.lplea: 


A,SW*IT 


SUBMIT Prompts YOU for the name of the SUB 
file and any arguments. 


A r S W * I T SWL 


SUBMIT executes the cownands found In the 
SUBA.SUB file. 


SUBMIT execvres the commands ~n AA.SUB. 
CeplaElng .I1 
oEsvrrenseo of $1 with the 


argument zz and a l l oocurrenoes of $ 2 with 
5 2 . 


The PROIILB.SUB Start-up Pile; 


Every rime you parer up or reset your 
Computer, CP/M Plus looks for a specla1 
SUBMITfile named PROFTLE.SUB to execute. 
If the file does nor er,sr, 
CP/M Plus 


r e s u m e s n o r m a l operation. 
If t h e 


PROFILE.SUB file exists, the system 
executes the .orn.na. 
in the file. This 
file is convenient to use if you regularly 
execute a set of cornandl before you do 
your regular session on the computer. 


CP/M Plus Command Summary 


NPE 


TYPE 
TYPE fileapes 
TYPE filespec lPACBl 
TYPE filespec INOPAGEI 


SurP3.e: 


The TYPE command displays the contents of an 
ASCII charactell file on your acreen. 


IPAGBI 
Causes the console listing Lo 
be displayed in paged node8 
t h a t IS, atop automarisally 
aftec llsrlng n lines of t e x t . 
where n nornallv defaults to 
24 lines per page. 


B X a q l e . . 


FIPIIOC.PP* 


Dlsplaye =he oontenls of the file HYPROC.PLI on 
your screen. 


B:TglSllm [PAGE1 


Dieplaya the Eonrents of the flle TBISPILE Lrm 
drive B on your screen 24 lines at a Lime. 


CP/M 
cornand sumary 


USER 


mrp0s.i 


ma unsa comma sets the current user 
number. The disk dlreotory can be divided 
ink0 diBtinct gxoups according to a User 
W e r . Usex numbers range from 0 through 
15. 


b.41.S. 


A > O m 
m t s r usar*,s 


51ir 
m CYX~CIII 
riser numb~x 1. 
n 
a 
5 on drive 


li. 


Thl. 
co.n.na 
0n.ng.s 
th. 
surr.nt 
user 


number to 3. 


XREF 


sy"rsl: 


XRBP id:) filename {SP) 


b.a.p1e.: 


A>- 
b : l U P m 


XRBP opexarss on the files M Y P R L I C . ~ ~ 
and 


"YPROC.Pmon drrve B:, pxoduclng the file 
8:MYPROC.XRF. 


A>- 
b:*rPaDC SP 


=he SP option directs the output to the 
printer. 


DIGITAL 
RESEARCH" 


SIDTM 


Productivity Tool 
Command Summary 


e o w w w 


c~rvr,enx @ ~ w a 
or o,o,tal ~e,sarcn m c at, rsn-r rerewed 


NO pan 01 ,",8 
D"ll,<l,O" 
may be rrlrodured Irsnrrnllted. 


tr8"8El,bed. atorad In a retnsua, system. or aansloted #"to any 


I."BY.la 
Or CDmPYler lana"a9e In any ,arm or by any menns. 


e~ectron~c. mmcnanma~, magns~c. optical rnemeca8. mnnua!, or 


DIheIWIsL WlthOYf tns pr,or *,,,ten 
Permisslo" 
0' 
Ols8l.I 


Rssaerch Inc. Post Mtlre Box 519. P.oitis 
Oroue. Callfornls 


93950 


DISCUIMER 


Dlgll.1 
RLSBarch Inc maker no rspresenrsllonr or warranller 


Wll" rrsoart to ,he contenla ".,.or 
and SDeslflCall" dllclalmr 


8"" 
ImDlirl w.rr.n,,*s 
of merc".nlll#l#,y or fltnerl tor any 


P.'IlCYI.. 
o...... 
FYnhe.. ......I...................... 


rig", to .LYIS. 
,hi3 rvalicatlon and to mahe snanse, trom 


,,me to timr 
8" 
the content "arLof WlrnDul obllgsllon 0' 


D181111 RB38en-h 1°C 
to "Dl,'" 
any person or 8°C" 
reurlon or 


rnangsr 


T M D E M I R I I 


CP/M 
and 01911.1 
R13aarsb 
aria 
I s Iogo are rsglrtarsd 


Irademartr of O8glf.l 
ResLarch In. 
SIO and MAC are 


,nbam.r*r 
01 Dlgltal RIIsa.cn 
1°C 
Intel r a reQ8"t"Bd 


Inbarnark of I",., 
Corporatlan 


7"s SID ProdUCrlvitV TO., 
Command lummarv war prepare* 


using the Dlgltsi Rarsarch TIX-Text IDrmal<er and prnled in 


ths Unltsd States of Arnerca 


SID"C0MMAND SUMMARY 


STARTUP 


(1) 
SID 


(2) 
SID x.y 


(3) 
SID x.HEX 


(4) 
SID x.UTL 


(5) 
SID x.y u.v 


Form (1) starts SID without a test pro- 
gram, (2) loads the test program x.y (y 
is normally COM), (3) loads x.HEX in 
Intel "hex" format (4) loads and executes 
utility x, (5) loads x.y with the symbol 
table 
u.v (normally x.SYM). 
Example: 
SID SORT.COM SORT.SYM 


RmPONSE 


(1) 
# 


(2) 
SYMBOLS 


(3) 
NEXT PC 
END 
nnnn 
pppp 
eeee 
Form (1) indicates SID is ready to accept 
commands, (2) indicates machine code 
loaded 
commencing symbol table load, 


(3) sho)ws successful machine code and/or 
symbol load where nnnn, pppp, and eeee 
are hexadecimal values giving the next 
unfilled machine code location, the initial 
program counter, and the last free mem- 
ory location, respectively. 


LElTER COMMANJX 


A 
Assemble 
M 
Move 
C 
Call 
P 
Pass Point 
D 
Display 
R 
Read 
F 
Fill Memory S 
Set Memory 
G 
Go 
T 
Trace 
H 
Hex 
U 
Untrace 
I 
Input Line 
X 
Examine 
L 
List Mnemonics 


1 


COMMAND LINE 


SID reads commands from the system 
console following the # prompt. Each 
command line is based upon the command 
letter and optional symbolic expressions. 
All CPIWline editing is available on 64 
character lines terminated by carriage 
returns. 
A space serves as a comma 
delimiter. 
SID terminates whenever 
control-C is typed. 


LITERAL NUMBERS 
SID uses the hexadecimal number base, 
consisting of the decimal digits 0-9 along 
with the hex digits A-F. 
Numbers ex- 
ceeding four digits are truncated to the 
right. 
Examples are: 
30 3F 3f FF3E F3 


DECIMAL NUrnERS 


Decimal numbers are preceded by a II, 
and consist of decimal digits 0-9. 
Num- 
bers exceeding 65535 are truncated to 
the rightmost 16 bits. 
Examples are: 
#48 $9999 #65535 $0 


CHARACTERS 


SID accepts graphic ASCII characters 
within 
paired 
string 
apostrophes (9. 


Strings of length greater than two are 
truncated to the ripht. 
The riEhtmost 


character of a two character st6ng be- 
comes the least significant byte. 
A one 
character string has a high order 00 byte, 
zero length strings are disallowed, and a 
pair of apostrophes within a string re- 
duces to a single apostrophe. Lower case 
letters are not translated in strings. Ex- 
amples are: 


va, 
'A' 
txy' 
'If", 


SYMBOL REFERENCES 


SID symbolic expressions may involve 
symbol references when a symbol table 
is present: 
1 
.s 


(2) 
@S 


(3) 
=s 


Form (1) denotes the address of symbol 
s, (2) denotes the 16-br- 
at .s, (3) 


denotes the 8-bit value at .s where s is 
a sequence of characters hatching a 
symbol table element. 


QUALIFIED SYMBOLS 


SID searches for a symbol match starting 
a t the first symbol loaded until the first 
symbol matches. When duplicate symbols 
exist, a qualified reference of the form: 


Sl/S2/ . . . Isn 


matches symbols from left to right as 
the search proceeds sequentially through 
the symbol table. 
An example is: 


ALPHA/GAMMA/I 


SYMBOLIC EXPRESSIONS 
Expressions consist of a left to right 
sequence of literal numbers, decimal 
numbers, character strings, and symbol 
references, separated by plus P+") and 
minus ('C") operaton. 
Values are added 
or subtracted, accordingly, with no over- 
flow checks, to produce the final 16-bit 
result. 
a leading minus, as in -x, is 
computed as 0-x. 
A leading plus, as in 
+x, is computed as x8+x, where x' is the 
value of the last expression q y d . 
A 
sequence of n K p r o d u c e s e n 
stack- 
ed value in the program under test (see 
the G command). Blanks are not allowed 
within expressions. 
Examples are given 
with individual commands. 
3 


A """ 
(1) 
As 


(2) 
A 


(3) 
-A 


Form(l) begins in-line assembly a t loca- 
tion s, where each successive address is 
displayed until a null line or "." is entered 
by the operator. Form (2) is equivalent 
to (1) with assumed starting address de- 
rived from last assembled, listed, or 
traced address. 
Form (3) removes the 


assemblerldisassembler module, discards 
existing symbol information, and disables 
subsequent A or L commands. 
In this 
case, machine hex code is displayed in 
subsequent traces. 
Examples: 


A100 
A#100 


A.CRLF+S 


A@GAMMA+@X-=I 


A+30 


(3) 
Cs;b,d 


Form (1) performs a direct Call from SID 
to location s in memorv. without dis- 
tirbing the CPU state of the program 
under test, and is most often used with 
SID Utilities. 
In this case, registers 


BC=OOOO DE=0000. Form (2) calls s with 
data BC:~, DE=0000, while form (3) also 
fills DE-d. 
Examples: 


ClOO 


C#4096 


C.DISPLAY 


C@JMPVEC+=X 


C.CRLF,#34 


C.CRLF,@X,+=X 


D D*PLAY 
&IEMoRY 


(1) 
Ds 


(2) 
Ds,f 


(3) 
D 


(4) 
D,f 


( 5 ) 
DWs 


(6) 
DWs,f 


(7) 
DW 


(8) 
DW f 
Form (1) types kemory contents in 8-bit 
format starting at location s for f screen 
with graphic ASCII to the right of each 
line, (2) is similar, but ends a t location 
f. 
Form (3) continues the display from 
the last displayed location, or the value 
of the HL register pair following CPU 
state display, for t screen, (4) is similar, 
but terminates a t location f. 
Forms ( 5 ) 


through (8) are equivalent to (1) through 
(41, but display in word format (16-bits). 
Examples: 


DF3F 


D#100,#200 


D.gamma,.DELTA+#SO 


d,.GAMMA 


DW@ALPHA,+#lOO 


Fs,f,d 


Fills memory with 8-bit data d starting 
a t location s, continuing through location 
f. 
Examples: 


FlOO,3FF,ff 


f.gamma,+#l00,#23 
F@ALPHA,+=I,=X 


5 


(1) 
G 


(2) 
Gp 


(3) 
G,a 


(4) 
Gp,a 


( 5 ) 
G,a,b 


(6) 
Gp,a,b 


(7) 
42 . . . 
Form (1) starts the program under test 
from the current PC without breakpoints. 
Execution is in real time. 
Form (2) is 
equivalent, but sets PC=p before exe- 
cution, (3) starts from the current PC 
with a breakpoint at location a, (4) is 
similar to (3) but sets the PC to p. Form 
( 5 ) is equivalent to (3) but sets break- 
points at a and b, while (6) presets the 
PC to p before execution. Upon encoun- 
tering a breakpoint (or an externally pro- 
vided RST T), the break address is printed 
in the form: 


*nnnn 


and the optional breakpoints are cleared. 
Forms given by (7) parallel (1) through 
(6), except "pass points" are not traced 
until the mrresponding pass count be- 
comes zero (see F command). The symbol 
"4" in an expression produces the topmost 
stacked value, which is used to set a 
break following a subroutine call. Given 
that a breakpoint has occurred at a sub- 
routine, the command 


G,+ 


continues execution with a return break- 
point set. 
Examples: 


GI00 


G100,103 


G.CRLF,.PRINT,#l024 


G@JMPVEC+=I,.ENDC,.ERRC 


G,.errsub 


G,.ERRSUB,+SB 
-~100,+10,+1B 
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H "" """ 
(1) 
Ha,b 


(2) 
Ha 


(3) 
H 
Form (1) produces the hexadecimal sum 
(a+b) and difference (a-b) of operands. 
Form (2) performs number conversion by 
typing the value of a in the format: 
hhhh #ddddd 'c' .ssss 


where hhhh is a's hex value, dddd is the 
decimal value, c is the ASCII value, if 
it exists, and ssss is the symbolic value, 
if it exists. 
Form (3) prints the hex 


values for each symbol table element 
(abort with rubout). 
Examples: 


H100,200 


H#1000,#965 


H.GAMMA+=I,@ALPHA-#10 


H#53 


HQX+=Y-5 


......................... 
,.,.,,.,,,.,., ,.,. ......................................................................... 
" ,,,,,,,,,, 


I 
mPuT 


Initializes default low memory areas for 
the R command or the program under 
test as if the characters c 
through c 
had 'been read and setup at1 the consolg 
command processor level. Default FCB's 
are initialized, and the default buffer is 
set to the initial input line. 
Examples: 
I x.dat 


ix.inp y.out 


I s:x.inp b:y.out $-p 


ITEST.COM 
I TEST.HEX TEST.SYM 


7 


(4) 
:L ... 
Form (1) lists disassembled machine code 
starting a t location s for f screen, (2) 
lists mnemonics from location s throu h 
f (abort typeouts with rubout). Form &) 
lists mnemonics from the last listed, as- 
sembled or traced location for t screen. 
Form (4) parallels (1) through (3). but 
labels and symbolic operands are not 
printed. 
Labels are printed in the form 


ssss: 


ahead of the lines to which they corres- 
pond. 
Non-8080 mnemonics are printed 


8s 


??= hh 
where hh is the hex value at that loca- 
tion. 
Examples: 


LlOO 


L#1024,#1034 


L.CRLF 


L@ICALL,+SO 


-L.PRBUFF+=I,+'A' 


. ............................... .,. ,,,,,,,,,,,,,, .,,.,.,. ,,,,,, . ,,,,,,,,, .,.,.,,.,. ,,,,,, . ,,,,,,,, . ,,,,,,,, . ,,,, .................... 
M MOVE MEMORY 


Move data values from start addresc s 
through 
address h to destination address 
d. 
Data areas may overlap during the 
move process. 
Examples: 


M100,1FF,300 


M.X,.Y,.Z 


M.GAMMA,+FF,.DELTA 
M@alpha+=x,t#50,+100 


P 


PASS 


(1) 
PP 


(2) 
PP,C 


(3) 
P 


(4) 
-pp 


(5) 
-P 


A "pass point" is a program counter loca- 
tion to monitor during execution of a 
test program. 
A pass point has an as- 
sociated "pass counter" in the range 1-FF 
(0-#255) which is decremented each time 
the test program executes the pass point 
address. 
When a pass count reaches 1, 
the pan point becomes a permanent 
breakpoint and the pass count remains 
at 1. Unlike a temporary breakpoint (see 
G), pass points with pass count 1 stop 
execution followin execution of the in- 
struction a 
d 
a 
k 
address. Form (1) 


sets a pass point a t address p with pass 
count 1, (2) sets pass point p with pass 
count c, (3) displays active pass points 
and counts, (4) clears the pass point a t 
p (equivalent to Pp,O), and (5) clears all 
pass points. 
Up to 8 pass points can be 
active at any time. 
CPU registers are 
displayed when executing a pass point, 
with the header 
nn PASS hhhh .ssss 


showing the pass count nn and address 
hhhh with optional symbol ssss. Registers 
are not displayed if -G or -U is in effect 
until the pass count reaches 1. Execution 
can be aborted during the pass trace with 
rubout. 
Examples: 


PI no FC 


R READ CODBBYMBOLS 


(1) 
R 


(2) 
Rd 
The I command sets up code and symbol 
files for subsequent loading with the R 
command. Form (1) reads optional code 
and optional symbols in preparation for 
pmgram test, (2) is similar, but loads 
code and/or symbols with the bias value 
d. 
The sequence: 
I x.y 
R 
Sets up machine code file x.y (y is usually 
COM), and reads machine code to the 
transient area. 
If y is HEX, the file 
must be in Intel "hex" format. 
The 
sequence: 
I x.y u.v 
R 


also reads the symbol file u.v (u is usually 
the same as x, and v is normally SYM). 
The form: 
I * u.v 
R 


skips the machine code load, and reads 
on$ 
the symbol file. 
When a symbol 
file is specified, the response 
SYMBOLS 


shows the start of the symbol file read 
operation. Thus, a "?" error before the 
SYMBOL mesage indicates a-hine 
code read error, while "?" following the 
SYMBOL message shows a symbol file 
read error. 
Examples: 
I COPY.COM 
R 
I SORT.HEX SORT.SYM 
R 
1 merge.com merge.sym 
RlOOO 
I * test.sym 
R-#256 
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S 
(1) 
s s 


(2) 
sws 


Form (1) sets memory locations in 8-bit 
format, (2) sets memory in 16-bit "word" 
format. 
In either case, each address is 
displayed, along with the current content. 
If a null tine is entered, no change is 
made, and the next address is prompted. 
If a value is typed, then the data is 
changed and the next address is pmmp- 
ted. Input terminates with either invalid 
input, or a single "." from the console. 
Long ASCII input is entered with form 
(1) by typing a leading quote (") followed 
by graphic characters, terminated by a 
carriage return. The examples show un- 
derlined console input: 


SlOO 
m c 3 34 
0101 24 m 
4 


0102 CF- 
0103 48 "Ascii 
0108 6E 
0109 D4 - 
SW.X+#36 
- 
D 
44F 
2302 4B32 mAMMA 
2304 3382 - 
2306 F F l l n+.X+=I-#20 
2308 348F -- 


T .IxACE 
(1) 
Tn 


(2) 
T 


(3) 
Tn,c 


(4) 
T,c 


(5) 
-T . . . 
(6) 
TW . . . 


(7) 
-TW . . . 
Form (1) traces n program steps, showing 
the CPU state at each step, while (2) 
traces one step. 
Form (3) is used with 


SID utilities, and "cans" the utility func- 
tion c at each trace step. 
Form (4) is 


similar to (3) but traces only one step. 
Form (5) parahels (1) to (4) but disables 
symbols. 
Form (6) paralllls (1) to (4), 


but performs "trace without call" showing 
only local execution. Form (7) is similar 
to (6) with symbols disabled. Examples: 


TlOO 


TX3O,.COLLECT 


-TW=1,3E03 


.............................. 
,,,, .,.,,,.,,.,.,,,. ,,,,,,,, .,.,,. ,,,,,,,,,,,,, ............................ 
,,,, .,.,.,,.,.,.,. 


U 
(1) 
u . . . 


(2) 
-u 


(3) 
UW . . . 


(4) 
- u w . . . 


U performs the same function as T, ex- 
cept the register state is not displayed. 
Forms (2) and (4), however, disable inter- 
mediate pass point trace (see P). U and 
T both run fully monitored, with auto- 
matic breaks at each instruction. Execu- 
tion can be aborted with rubout. 
Exam- 
ples: 


Uffff 


Ub10000,.COLLECT 


UW=GAMMA,.COLLECT 
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(1) 
X 


(2) 
Xf 


(3) 
Xr 
Form (1) displays the CPU state in the 
format: 
f A=a B=b D-d H-h S=s P=p i s 
where f is the "flag state," a is the 8080 
accumulator content, b is the 16-bit BC 
register pair value, d is the DE value, h 
is the HL value, s is the SP value, p, is 
the PC value, i is the decoded instructlon 
a t p, and s is symbolic information. The 
flag are represented by dashes P-") when 
false, and their letters when true: 
Carry Zem Minus Even parity 
- 
Interaigit cFmy 


Form (2) allows flag state change, where 
f is one of C,Z,M,E, or I. 
The current 


state is displayed (either 'L" or the let- 
ter). 
Enter the value 1 for true 0 for 
false, or null for no change. 
~ i r m 
(3) 


allows register state change, where r is 
one of A, B, D, H, S, or P. 
Symbol 
information is given at s when i refer- 
ences an address, including LDAX and 
STAX. 
The form "=mm" is printed for 
memory referencing instructions (ex., 
INR M, ADD MI, where mm is the mem- 
ory value before execution. 
Examples 
with o p e r a t o r p u t underlined: 


XM - 


! 
B 
:BO 


m 
4 
SEPF 


XP 
m E .CRLF+lO 


13 


sm mpms 


Utilities execute w ~ t h SID to provide 
additional debugging facilities. A utility 
is loaded initially by typing: 


SID x.UTL 


where x is the utility name. 
Upon load- 
ing, the utility is setup for execution 
with SID, and responds with: 
.INITIAL = iiii 
.COLLECT = cccc 
.DISPLAY = dddd 
where iiii, cccc, and dddd are three abso- 
lute address entries to the utility for 
(re)initializing, collecting debug data, and 
displaying collected information, respec- 
tively. 
The SID symbol table contains 
these three entry names. 
A utility is 
reinitialized by typing: 


Ciiii 
or 
C.1NITIAL 


The display information is obtained by 
typing: 


CWdd 
or 
C.DISPLAY 


while data collection occurs during moni- 
tored execution using the T or U com- 
mands, where the second argument gives 
the collection address. 
Examples are: 


Uffff,.COllect 
U#1000,3403 


TWlOOO,.COLLECT 


UW@GAMMA,.COLLECT 


Pass points may be set during data col- 
lection to stop the monitoring a t the end 
of program areas under test. The actual 
initialization, 
collection, 
and 
display 
functions depend upon the particular SID 
utility. 


I4 


The HlST utility creates a histogram of 
pmgram execution between two locations 
given during initialization. Pmgram ad- 
dresses are monitored during U or T mode 
execution, with summary data displayed 
a t any time. Upon startup or reinitiali- 
zation, HIST pmmpts with: 
TYPE HISTOGRAM BOUNDS: 


Respond with: 


aaaa,bbbb 


for a histogram between locations aaaa 
and bbbb, inclusive. 
Collect data in U 


or T mode, then display results. 
Output 
is scaled to the maximum collected 
value, accumulating until reinitialization. 
An example: 


SID HIST.UTL 
-RAM 
BOUNDS 


.INITIAL = 3E03 


SFMBOLS 
#UFF .COLLECT 
(regis;er display and break) 
#C.DISPLAY 
(histogram display) 
UlOOO .COLLECT 
{display and eventual break) 
C.DISPLAY 
{updated hktogram display) 
# C.INITIAL 
(histogram bounds reset) 


TAB TRACE UTILJTY 


The TRACE utility provides a dynamic 
backtrace of up to 256 instructions which 
ended at the current break address. In- 
struction address collection occurs on1 
in U or T mode. 
Pass points c a n i 
active, however, during the data collec- 
tion, and will halt execution when the 
pass count becomes 1. 
Initialization 
clean the accumulated instructions, col- 
lection records the instruction address in 
a wraparound buffer, and display prints 
the backtrace in decoded mnemonic form 
with symbol references and labels when 
they occur. 
If "-A" is in effect, only 
instruction addresses are given. 
In this 
case, TRACE is loaded by typing: 


An example of normal operation: 
SID TRACE.UTL 
READY FOR SYMBOLIC BACKTRACE 
#I MERGE.COM MERGE.SYM 


IMPLEMBNTATION NOTES 


The SID program operates in about 6K 
bytes and self-relocates directly below 
the BDOS (overlaying the CCP area). 
The SID symbol table fills downward from 
the base of SID. As the table fills, the 
BDOS jump address is altered to reflect 
the reduced free space. Programs which 
"size" memory using the BDOS jump ad- 
dress should not be started until all sym- 
bols ere loaded. 


The 'LA'' command increases the free 
space by about 1 t K bytes. 
Any existing 
symbol information must be reloaded af- 
ter issuing the command. 


Programs will trace up to the BDOS 
where tracing is discontinued until con- 
trol returns to the calling program. ROM 
subroutine tracing is discontinued when 
ROM is entered through a call, jump, or 
PCHL, and resumed upon return to the 
calling program in RAM. 


Use rubout to abort programs running 
fully monitored in T or U mode, and an 
externally provided restart (RST 7) when 
running unmonitored with G. 


The 8080 mnemonics which follow (repro- 
duced with permission from Intel@Cor- 
poration), can be entered directly in as- 
sembly mode (see A), and are produced 
by SID in list mode (see L). 
Data fields 
can consist 
of symbolic expressions. 
Given that "A100" has been typed, and 
that the symbols X, Y, and Z exist, the 
following is valid input: 


MOV A,B 
MYI 
A,FF 


mvi 
b,#255 


MY1 
M,'xt 


LXI 
H,'ab' 


JMP 
100 
CALL .X 
JZ 
@Y 


lxi 
h,@X+=Z 


JMP 
.X/Y+5 


Notable differences between MAC"and 
the SID "A" command are that no pseudo 
operations are allowed, operands are SID 
symbolic expressions*, labels cannot be 
inserted, and register references must be 
names, not numbers. 


*In particular, note that 
LXI H,'ab' 


fills H with 'a' and L with 'b' due to the 
nature of SID expressions, which is coun- 
ter to the MAC convention. 


C3 JMP 
C2 JNZ 


02 JNC 


EA 
JPE 


F2 
JP 


CPO 
CPE 
CP 
CM 


01 
INR 
B 


OC 
INR 
C 


11 INR 
D 


1C INR 
E 
24 
INR 
H 


2C 
INR 
L 


34 
INR 
M 


3C 
INR 
A 


05 
DCR B 


OD 
DCR C 
15 
DCR D 


I D DCR E 
25 
DCR H 


20 DCR L 
35 
DCR M 


3D 
DCR A 


RET 
RNZ 
RZ 
RNC 
RC 
RPO 
RPE 
RP 
RM 


W 
DAD B 


19 
DAD D 


29 
DAD H 
39 
DAD SP 


M L D M B 
1A 
L D M D 


ZA LnLD ~r 
3A 
LDA 
M r 


03 
INX 
B 
08 
DCX B 
02 
STAX B 


13 
INX 
D 
1B DCX D 
12 
STAX D 
n INX 
n 
2s DCX H 
22 
SHLD Adr 


33 
INX 
SP 
38 DCX SP 
32 
STA 
M r 


08 - matmt. or loswvmmw ex- 
mat 


to an 8 bl data quanllv. 
' - all Flqs IC. Z. S. P. A q aflmec 


C7 
RST 
0 


CF 
RST 
I 


07 RST 
2 
DF RST 
3 
E7 
RST 
4 
EF RST 
5 


W RST 6 
FF 
RST 
7 


C5 
PUSH 0 


D5 
PUSH D 
E5 
PUSH H 
F5 
PUSH PSW 


C1 
POP 0 


Dl 
POP D 


E l 
POP 
H 


F1 
POP 
PSW' 


E3 
XTHL 


FS 
SPHL 


EB XCHG 
27 
DAA' 


2F 
CMA 
37 
STC+ 


3F 
CMCt 


07 
RLC 
OF 
RRC 
17 
RAL 


1F 
RAR 


W 
NOP 
76 
HLT 
F3 
Dl 


FB 
El 


40 
MOV 0.0 
41 
MOV 0.C 


42 
MOV B.D 
43 
MOV 0.E 


44 
MOV 6.H 


45 
MOV O.L 


46 
MOV O.M 
47 
MOV O.A 


48 
MOV C.0 


49 
MOV C.C 


4A 
MOV C.D 
40 
MOV C.E 
4C 
MOV C.H 


40 
MOV C,L 


4E 
MOV C.M 


4F 
MOV C,A 


50 
MOV D.O 


51 
MOV D C 
~ 
~ 


52 
MOV D,D 
53 
MOV D.E 


54 
MOV D.H 


55 
MOV D,L 


56 
MOV D.M 


57 
MOV D,A 


58 
MOV E,B 
59 
MOV E.C 
5A 
MOV E D 


50 
MOV E.E 
5C 
MOV E,H 


50 MDV E.L 
5E 
MOV E.M 


5F 
MOV E.A 


MOV H.0 
MOV H.C 
MOV H,D 
MOV H.E 
MOV H,H 
MOV H.L 
MOV H.M 
MOV H,A 


MOV L.0 
MOV L.C 
MOV L.D 
MOV L.E 
MOV L H 
MOV L.L 
MOV L.M 
MDV L.A 


MOV M.0 
MOV M,C 
MOV M.D 
MOV M.E 
MOV M.H 
MOV M.L 
.. 
.. 


MOV M.A 


MOV A.O 
MOV A.C 
MOV A,D 
MOV A,E 
MOV A.H 
MOV A.L 
MOV A.M 
MOV A.A 


~ 1 6 
= mnotant, or log,caVaritnrnetro expm.son 
that evaluates 


10 a 36 blt data quant,I" 


t = onb CARRY anected 


A8 
XRA 
B 


80 
ADD 
B 
A9 
XRA 
C 
81 
ADD 
C 
PA 
XRA 
D 


82 
ADD 
D 
AB 
XRA 
E 
83 
ADD 
E 
AC 
XRA 
H 


64 
ADD 
H 
AD XRA 
L 
85 
ADD 
L 
AE 
XRA 
M 


68 
ADD 
M 
AF 
XRA 
A 
87 
ADD 
A 


80 
ORA 
B 


66 
ADC 
B1 
ORA C 


89 
82 
ORA 
D 


6A 
83 
ORA E 


ADC 
8 4 
DRA H 


6C 
" 
85 
ORA L 


6 0 ADC L 
66 
OR* M 


8E 
ADC 
8 1 ORA A 


8F 
ADC 
A 


90 
SUB 
B 
:: :/; 


BA CMP D 
BB 
CMP 
E 
BC CMP H 


95 
SUB 
L 
CMP 


96 
SUB 
M 
:E :/; 


97 
SUB 
A 


9C 
5 8 8 H 


9 0 SBB 
L 


9E 
SBB 
M 


SF 
SBB 
A 


A0 
ANA 
B 


A? 
ANA 
C 
A2 
ANA 
D 


A3 
ANA 
E 
A4 
ANA 
H 
A5 
ANA 
L 
A6 
ANA 
M 


A7 
ANA 
A 


Adr = 16 M address 
.. = 811 Flags BXCBP~ CARRY an~~lsd: 


lexcepflon INX & DCX anect no Flags1 
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Foreword 


CP/M* 3 a a microcomputer operating system designed for the Intele 8080, Intel 


8085, or other companble micropmcssor. To run CP/M 3, your computer must 
have an ASCII console, which includes a keyboard and screen, or another display 
dcvlce, from one to sixteen disk drives and a mrnlmum of 32K of memory space. To 
support additional memory beyond the 64K addressing limit of the processors listed 
above, CP/M 3 can also suppon bank-switched memory. The minimum memory 
requirement for a banked system is 96K. 


Thm manual de~ribes the programmxng environment of CP/M 3, and is written 
for experienced programmers who are writing applzcation software in the CP/M 3 
environment. It assumes you are familiar with the system featurn and utilities described 
in the CP/M PIUS (CP/M Version 3) Operating System User's Gutde and the 
Progrmnmer'r Uttlitier Guide for the CPlM Famzly of Operating System. It also 
assumes that your CPlM 3 system has been customized for your computer's hard- 
ware and is executing as described in the CP/M Plur (CPIM Version 31 Operating 
System User's Guide. If you need to customize your system, please refer to the CP/M 
Plur (CPIM Vmion 3) Operating System System Guide. 


Smmn 1 of this manual describes the components of the operating system, where 


they resldc in memory, and how they work together to ~rovidc a standard operating 
environment for application programs. Section 2 describes how an application pro- 
gram can call on CP/M 3 to perform serial input and ourput and manage disk files. 
Section 3 provides a detailed description of each operatnng system function. Section 
4 prexnn example programs. 


The CPIM Plrrr (CP/M Verria 3) Opergting System Progrommcr'r Guide contains 


five aooendixes. Aomdix A describer the CPlM 3 System Connol Bloek, m d defines 
- 
in fidds. ~ ~ ~ c n d u ' ~ 
supplies the format for the 
Rclacatablc Program. Appcn- 


dix C tells you how to generate System Page Relocatable files. Appendix D lists the 
ASCII Symbol Table, and Appendix E summarizes BDOS functions. 
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Section 1 
Introduction to CP/M 3 


This section introduces you to the general features of CP/M 3 with an emphasis 
- 
on how CP/M 3 organizes your computer's memory. The section begins by descr~bin~ 
the general memory organization of banked and nonbankcd systems and defines the 
programming environment they have m common. It then shows how CP/M 3 defines 
- 
memory space into standard regions for operating system modules and executing 
programs. Subsequent paragraphs describe the components of the operating system, 
how they communrcatc with each other and the application program, and in greater 
detail where each component and program is located in memory. After a brief inuo- 
- duction to disk organnatlon, the final section gives uamplcs of system operation. 


CP/M 3 is available in two versions: a version that supports bank-switched mem- 


ory, and a version that runs on nonbanked systems. CP/M 3 user the additional 
memory available in banked systems to provide functions that are nor present m the 
nonbankcd version. Far example, the banked versron of CP/M 3 supports file pass- 
- 
words; the nonbanked version does not. However, because a nonbanked system 
treats passwords the same way as a banked system does when password protection 


8 
is not enabled, an apphcation program can run under either system without mod& 
cation. 
- 


' 
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1.1 Bankcd/Nonbankcd Organization 
CP/M 3 Programmer's Guide 


1.1 Banked and Nonbanked Memory Organization 


The memory organization for a "onbanked CP/M 3 system is very simple, as 


shown in Ftgum 1-1. 


TOP OF MEMORY l=l 


Figure 1-1. Nonbrnkcd System Mmory Organization 


In the nonbankcd organization, physical memory consists of a single, contiguous 


region addressable from OOOOH up to a maximum of OFFFFH (64K-1). The shaded 
region below the operating system represents the memory space available for the 
loadmg and execution of transient programs. The clear area above the operating 
system represents space that GENCPM can allocate to the operating system for d!sk 
record buffers and dirmory hash tables, as described in the CP/M PI= (CP/M Ver- 
sion 3) Operating System System Guide. The minimum size of this area a determined 
by the specific hardware requirements of the host micracomputer system. 


CP/M 3 Programmer's Guide 
1.1 Bankcd/Nonbanked Organization 


To expand memory capacity beyond the 64K address space of an 8-bit miaopro- 


-r, 
CP/M 3 supporn bankswitched memory in a s-l 
vmion called the baked 


svstem. In the banked version. the oneratine svstem is divided into two modules: the 
. 


restdent pomon and thc banked ponnon The rcrndcnt ponlan rcr~dcr I" common 
memory, rhc banked pomon re,tdcs lust below the top of banked memory tn Rank U 
Fnpurc 1 2 show, mcmov organtrarlon under the banked rptcm 


(COMMON) 


MEMORY 


(BANK SWITCHED) 


LOW MEMORY 


BANK 0 
BANK N 


"W w 


Figm 1-2. B d e d System Memory O@ation 


- 
In Figure 1-2, Bank 0 is switched in or in context. The top region of memory, the 


common region, is always in m t t x t ; that is, it can always be referenced, no matter 
what bank is switched in. Figure 1-3 shows memory organization when Bank 1 is in 
- 
context. 


1.1 Bankcd/Nonbanked Organization 
CP/M 3 Programmet's Guide 


TOP OF MEMORY * 


(COMMON), 


TOP OF BANKED ) 


MEMORY 


(BANK SWITCHED) 


LOW MEMORY 


(OOOOHI - 


BANK 0 
BANK l 
BANK N&"m* 


Figure 1-3. Banked Memoly with Bnnk 1 in Context 


From a transient program's perspective, Bank 1 is always in mntcn. The operating 
system can switch to Bank 0 or other bank when performing operating system 
functions without affecting the execution of the transient program. Any bank-switch- 
ing performed by the operartng system is completely transparent to the calling pro- 
gram. Because rhe major portion of rhe operating system resides in Bank 0 m banked 
systems, more memory space is available for transient programs in banked CP/M 3 
systems than m nonbanked systems. 


The operaring system uses the dear areas in Figures 1-2 and 1-3 for disk record 


buffers and directory hash tables. The dear area in the common region above the 
operating system reprevnn spacc that can be allocated for data buffers by GENCPM. 
Again, the minimum size of thls area is determined by the specific hardware rcquire- 
ments of the host microcomputer sjstem. 
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CP/M 3 Pmgrammn's Guidc 
1.1 Bankcd/Nonbanked Organization 


- 
The banked version of CP/M 3 requires a minimum of two banks, Bank 0 and 
Bank 1, and can suppon up to 16 banks of memory. Bank numbers arc generally 
arbitrary with the following exceptions: Bank 0 is the system bank and is in context 
when CP/M 3 a started. Bank 1 is the transient program bank, and musr be contig- 
- 
uous from location zero to the top of banked memory. This requirement does not 
apply to the other bank. However, common memory must be contiguous. 
- 
The size of the common region is typically 16K. The only sire requirement on the 
common region is that it must be large enough to contain the resident portion of the 
operaung system. The maximum top of memory address for both banked and non- 
- 
banked systems is 64K-1 (OFFFFH). 


In summary, no matter how physical memory is configured, or whether the oper- 
ating system is banked or nonbanked, CP/M 3 always organlrcs memory logically so 
- 
that to a transient program in any CP/M 3 system, memory appears as shown m 
Figure 14. 


TOP OF MEMORY r 


Figure 1-4. CP/M 3 Logical Mmory Organization 
- 


1.2 System Components 
- 
Functionally, the CP/M 3 operating system 3s composed of distinct modules. Tran- 
sient programs can communicate wlth these modules to request system services. Fig- 
ure 1-5 shows the reions where thex modules reside in loelcal memom. Note that 
- 
from the transient program's perspeawe, Figure 1-5 is just a more detailed version 
of Figure 1-4. 
- 
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HIGH MEMORY. 


610s-BASE. 


BDOS-BASE. 


LOADER-BASE: 


CCP . CONSOLE COMMAND PROCESSOR 


OlOOH 


PAGE ZERO 


0000H' 
- 


Figrrc 1-5. System C o m p c n t s and Regions in Logical Mmory 
- 


'Ihc Bmc InpurOurput Systm, BIOS. 15 a hard~arrdc~cndrnt 
modulc that ddinn - 


the low-lcvcl ~ntcrfrcr to a pann~lar computer ryrrcm. It conrarnr the dcvcr-dnvnng 
routlncr necessary fur pcnphcral dcv~cr UO. 
- 


The Basic Disk Operating System, BDOS, is the hardware-independent module that 


e the logical nucleus of CP/M 3. It provides a standard operating environment for 
transient programs by making services available through numbered system function 
calls. 


7 


The LOADER module handles program loading for the Console Command Proms- 


sor and transient programs. Usually, thrr modulc is not resident when transient p m - 
grams execute. However, when it is resident, transient programs can access this 
module by making BDOS Function 59 calls. 


Resident System Extensions, RSXs, are temporary additional operating system - 


modules that can selectively extend or modify normal operating system functions. 
The LOADER module is always resident when RSXE are active. 
- 
- 


O DIGITAL RESEARCH' 


1-6 
- 


- CP/M 3 Programmer's Guide 
1.2 
System Components 


- 
The Tansicnt Program Area, P A , is the region of memory where transient pro- 
grams wecute. The CCP also w a r e s in this region. 


- 
The Console Command Pr-ror, 
CCP, 8s nor an operanng system module, but Br 


a ryrtcm pruvam that prexnn a human-oncnted ~nrcrfaa to CP M 3 for rhc user 


The Page Zero repion is not an operating system module either, but functions 
primarily as an interface to the BDOS module from the CCP and translent programs. 
It also contains critical ryrtem parameters. 


1.3 System Component Interaction and Communication 


This m i o n dcsuibes innramion and communicat~on between the modules and 


regtons defined in Section 1.2. The most significant channels of communication are 
benveen the BDOS and the BIOS, transient programs and the BDOS, and transient 
programs and RSXs. 
'I%= 
division of responsibility between the drfferent modules and the way they 


communicate with one another provide thrcc important benefits. Fint, because the 
operamg system is divided mm two modules--one that is configured for different 
hardware cnvironmcnu, and one that remains constant on every computer-CP/M 3 
software is hardware independent; you can port your programs unchanged to differ- 
mr hardware confiplrauons. Second, because all communication beoven transient 
programs and the BDOS is channeled through Page Zero, CP/M 3 transient programs 
execute, ~f sufficient memory is available, independent of configured memory size. 
Third, the CP/M 3 RSX facility can customize the services of CPiM 3 on a selective 
basrs. 


1.3.1 T h e BDOS nod BIOS 


CP/M 3 achieves hardware independence through the interface between the BDOS 
and the BlOS modules of the operating system. This rnterface consists of a series of 
entry points in the BlOS that the BDOS calls to perform hardware-dependent pnmi- 
live functions such as peripheral device VO. For example, the BDOS calls the CONIN 
entry point of the BlOS t i read the next console input character 


A system implementor can customize the BlOS to match a specific hardware envi- 
ronment. However, even when the BIOS primitives are customized to match the host 
computer's hardware environment, the BlOS entry points and the BDOS remain 
constant. Therefore, the BDOS and the BlOS modules work together m give the CCP 
and other transient programs hardware-independent access to CP/M 3's facihtm. 
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1.3.2 
Applications and the BDOS 
- 


Tranr~rnt programs and the CCP access CP M 3 facrl~t~rs 
by maklng BDOS hnc- 


non call-. BDOS funcr~onr can create, drlcre, open, and close dirk filer, read or wrlte 
to opened files, retrieve input fmm the console, send output to the console or hst - 
device, and perform a wide range of other services described in Section 3,"BDOS 


To make a BDOS function call, a transient program loads CPU registers with 


specific entry parameters and calls location 000SH m Page Zero. If RSXs are not 
actwe m memory, location OOOSH contains a lump instruction to location 
BDOS-base + 6. If RSXs are active, location OOOSH contains a jump instruction to 
an address below BDOS-base. Thus, the Page Zero interface allows pmgrams m run 
without regard to where the operating system modules are located m memory. In 
addition, transient programs can use the address at location 0006H as a memory 
ceding. 


Some BDOS functions are similar to BlOS entrv ooints. oartl~larlv in the case of 
~ 
~ - - -~ 
~ 
~ - 
~~ 
.. 
.. 


rnmplc dewre 1 0 . For example, when a transtent program maker a conrolc output 
BOOS tunnlon call, the BDOS make, a BlOS conrolr ~,urpur call. In the case of d~rk 
1 0 , however, rhlr mlanonsh~p s more complex. The BDOS mtghr call many BlOS 
entry points to perform a single BDOS file UO bctton. 


Tranwcnt pmgam, .an rcrmtnatc cxrcutron by ]urnpang to lharton OOOUH In the 


Pafir 7rro rcg~on Thnr locarton conta~nr a lump mstru.rton to RlO\-base-3, 
w h ~ h 


conram a lump lnrtruitlon to the BlOS warm rran ruurlnc Ihr RlOS warm rran 
routine loads the CCP into memory at locat~on lOOH and then passes mntml to a. 


The Console Command Proassor is a special system program that executes in the 


TPA and makes BDOS calls just like an apphcation program. However, the CCP has 
a untquc role: it gives the user access to operating system facilities while transient 
programs are not executing. It lndudcs several built-in commands, such as TYPE and 
DIR. that can be executed directlv without havine to be loaded from dirk. When the 
CCP receives control, it reads the user's command lines, distinguishes between built- 
in and translent commands, and when necessary, calls upon the LOADER module to 
load transient programs from dmk into the TPA for execution. Scctlon 1.6.2 describes - 


CCP operatlo" in detail. 
- 
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1.3 Compotlcnt Interaction 


A Resident System Extension is a temporary additional operating system module. 
An RSX can a t m d or modify one or more operating system functions sdmxvcly. 
- As with a standard BDOS function, a transient program accesses an RSX function 


thmugh a numbered function call. 


- 
At any one time there might bc zem, one, or multiple RSXs active in memory. 
When a transient program makes a BDOS function call, and RSXs are active, each 
RSX uamincs the function number of the call. If the function number matches the 
function the RSX is designed to emend or modify, the RSX performe the requested 
- function. Otherwise, the RSX passes the function request to the next RSX. Noninter- 


cepted functions are eventually pased to the BDOS for standard execution. 
- 
RSXs arc loaded into memory whm programs containing RSXs am loaded. The 


CP/M 3 utility, GENCOM, can attach RSXs to program files. When attaching RSXs, 
GENCOM places a special one page header at the beginn~ng of the program file. The 
- CCP mads this header, learns that a program has attached RSXs, and loads the RSXs 
accordingly. The header itself is not loaded into memory; ~t merely indicates to the 
CCP that RSX loading ia required. 
- 
The LOADER module is a $pedal type of RSX that supporn BDOS function 59, 
Load Oveday. It 1s always resident when RSXs are anive. To indicate RSX support 
is required, a program that calls function 59 must have an RSX header attached by 
- GENCOM, even if the program docs not requrre other RSXs. When the CCP 


encounters this type of header in a program file when no RSXs arc active, it sets the 
address at location 0006H in Page Zero to LOADER-base+6 
instead of 


BDOS-bare + 6. 
- 


1.4 Memory Region Boundaries 
- 


This section reviews memory regions under CP/M 3, and then dneribcs some 
details of region boundaries. It then relates the sires of various modules to the space 
available for the execution of transient programs. Figure 1-6 revlcws the location of 
- regrons in logical memory. 


1.4 Region Boundaries 
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BlOS BASIC I10 SYSTEM 


BlOS-BASE 


BDOS BASE 


LOADER PROGRAM LOADER MODULE 
LOADER-BASE 


O l O O H 


PAGE ZERO 


OOOOH 


Figure 1-6. System Modules and Regions in Logical M-ory 


First note that all memory regions in CP/M 3 are page-aligned. This means that 


cegons and operating system modules must begin on a page boundary. A page is 
defined as 256 byns, so a page boundary always beg". at an address where the low- 
order bye is zero. 


The term High Memory in Figure 1-6 denotes the high address of a CP/M 3 
system. This address may fall below the a m a l top of memory address if space above 
the operating system has been allocated for directory hashing or data buffering by 
GENCPM. The maximum top of memory address for both banked and nonbankcd 
systems is 64K-1 (OFFFFH). 


The labclr RIOF-bau, BDOS-basc, and LOADFR-bau q 
m 
r 
rhc bau ad&- 


of the opcrat~ng system regonr These addr-r 
always fall on page houndancs Thc 


rnrr of rhc BlOS rcgon ~r not fixed, bur 1% dctcrmnncd by the rcqulrcmcnts of thc 
host computer system. 
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The size of the BDOS region differs for the banked and nonbanked versions of 


CP/M 3. In the banked version, the resident BDOS size is 6 pages, 1.5K. In the 
nonbanked system, the BDOS size rang- from 31 pages, 7.75K, to 33 pages, S.25K, 
depending on system generation options and 810s requirements. 


RSXr are page aligned modules that are stadred in memory below LOADER-base 
in memory. In thc configuration shown m Figure 1-6, location OO05H of Page Zero 
mntainr a i u m ~ 
to locauon R S X N base + 6. Thus the memory ceiling of the WA 
. . 
. - 


region is reduced when RSXs are active. 


Under CPiM 3, the CCP is a transient program that the BlOS loads into the W A 


region of memory at system cold and warm stan. The BlOS also loads the LOADER 
module at this time, because the LOADER module is attached to the CCP. m e n the 
CCP gains control, it relocates the LOADER module just bdow BDOS-base. The 
LOADER module handles program loading far the CCP. It IS three pages long. 


The maximum srze of a transient program that can be loaded into the TPA 1s 


ltmited by LOADER-base because the LOADER cannot load a program over melf. 
Tranacnr program. mry cxrcnd beyond rhs potnr, howcvcr, hy urtng mcmory ahove 
LOADER-bavc for unln~t~almed 
data areas such as I 0 buffers. Programs that urc 


memory ahove LIDOS-base cannot make BUOS hnctcon calls 


1.5 Disk and Drive Organization and Requirements 


CP/M 3 can suppon up to sixteen logical drives, idmuiied by the lmera A through 


P, with up to 512 megabytes of storage each. A logical drive usually corresponds to 
a physical drive on thc system, panicularly for physical drives that support remova- 
ble media such as floppy disks. High-capacity hard disks, however, are commonly 
divided up into multiple logical drives. Fiplrc 1-7 illustrates the standard organira- 
tlon of a CP/M 3 disk. 
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TRACK M 


DATA TRACKS 


TRACK N 


SYSTEMTRACKS 


TRACK 0 
wmr 


Figure 1-7. Dbk Owhation 


COLD BOOT LOADER 


In Rgure 1-7, the first N tracks arc the system tracks. System tracks are required 


only on the disk used by CPlM 3 during system cold start or warm start. The 
contents of this region are described in Section 1.6.1. All normal CP/M 3 disk access 
a directed to the data tracks which CP/M 3 uws for file smrage. 


The data tracks are divided into two regions: a directory area and a data area. The 
directory area defines the files that exist on the drive and identifies the data space 
that belong to each file. The data area contains the file data defined by the directory. 
If the drive has adequate storage, a CP/M 3 file can be as large as 32 megabytes. 


The directoq area is subdivided inm simm logically independent directories. Thac 


d~rectocier are ~dentified by user numbers 0 through 15. During system operation, 
CPlM 3 runs with the user number set to a single value. The user number can be 
changed at the console with the USER command. A transient program can change 
the user number by calling a BDOS function. 


The user number spcclfies the currently active directories for all the drives on the 
system. For example, a PIP mmmand to copy a file from one disk to another gives 
the destination file the same user number as the source file unless the PIP command - 
e modified by the [GI opnon. 
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- 
The directoty ~dentifies each file with an eight-character filename end a three- 


character filerype. Together, these fields must be unique for each file. Rler with the 
same filename and filetype can reside m diffemt user dirccmries on the same drive 
without conflict. Under the banked version of CP/M 3, a file can be assigned an 
- eight-character password to protect the file from unauthorized access. 


All BDOS functions that involve file operations specify the requested file by file- 
name and filetype. Multiple files can be specified by a technique called ambiguous 
reference, which uses question marks and asterisks as wildcard characters to give 
CPiM 3 a panem to match aa rt searches the dlrmory. A question mark in an 
- ambxguaus reference matches any value in the same position in the directory filename 
or filetype field. An asterisk fills the remainder of the filename or filetypc field of the 
ambiguous reference with question marks. Thus, a filename and filetypc field of all 
question marks, ????????.???, equals an ambiguous rehrencc of two asterisks, ..., 
- and marches all fils in the directory that belong to the current user number. 


The CP M 3 file ryrtcm auramat~cally allocates drrcclory spa- and data area space 
- when a 61r Br mated or extended, and returns prcv~ourly allouted space ro free 


space when P file 1 deleted or truncated If no dtmory or data space rs aua,lablr lor 
a requested operation, the BDOS returns an error to the calhng program. Ln general, 
- the allocation and deallocation of dirk space is transparent to the calling program. 


As a result, you need not be concerned with drrcfoty and drive organization when 
using the file system facilities of CP/M 3. 
- 


1.6 
System Operation 


This s m o n introduces the ecneral oneration of CP/M 3. This overview covers 
- 
- 
. 
- -~ 


toplcr conccrnlng the CP .M 3 ryrtcm components, how they hnct~an and how they 
lnrcract when CPhl 3 rr runn~ng. The scctlon d m not dcwr~br the total function- 
almry of CP .U 3, bur s~mply ~nrroducer has= CP M 3 opcrmonr. 
- 


For the purpose of this overview, CP/M 3 system operation is divided into k e 


categories. First is system cold start, the process that beens cxccuuon of the operat- 
- ing system. lhrs proadurn ends when the Console Command Processor, CCP, is 
loaded into memory and the system prompt is displayed on the amen. Second is the 
operation of the CCP, which provldcs the user interface m CP/M 3. Third is transrent 
program initlatlon, exccuuon and termination. Fourth is the way Restdent System 
- Extensions run under CP/M 3. The fifth and final category describes the operation of 


the CP/M 3 SUBMIT utility. 
- 
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1.6.1 Cold Start Operation 


The cold start procedure is typically executed immediately alter the computer is 


turned on. The cold start brings CP/M 3 into memory and gives it control of the 
computer's resources. Cold start is a four-stage procedure. 


In the first stage, a hardware feature, or ROM-based software assodated with 
system reset, loads a small program, called the Cold Bwr Loader, tnto memory from 
the system tracks of drive A (see figure 1-6). The Cold Boot Loader 1s usually 128 or 
256 byes long. 


The Cold Boot Loader performs the second stage of the cold start process. It loads 
the CP/M 3 loader program, CPMLDR, into mcmory from the system tracks of the 
system disk and passes control to it. Durmg this stage, the Cold Boot Loader can 
also perform other tasks, such as initializing hardware dependent VO ports. 


CPMLDR performs the third stage in the cold start process. First, it reads the 


CPM3.SYS file from the data area of the dirk. The CPM3.SYS file, which is created 
by the CP/M 3 system generation utility GENCPM, contains the BDOS and BIOS 
system components and rnformatlon tndicat~ng where there modules arc to rcssde in 
memory. Once CPMLDR has loaded the BDOS and BIOS into memory, it sends a 
agn-on message to the console and passes control to the BIOS Cold Bwr entry pomt. 
If specified as a GENCPM option, CPMLDR can also display a memory map of the 
CP/M 3 system. 


CPMLDR is a small. self-contained version of CP/M 3 that suowrts only console 
- - ~ 
--- - 
~ 
.. 
' 


output and sequentla1 file input. Consistent with CP/M 3's organization, it contains 
two mrw(n~lrr. an invariant CPMLDR BDOS. and a variant CPMLDR BIOS that is 
. .. 
.~~ 
- 
~ 
~ 
- 
~ 
~ 
--- --- -~ -- - - 
- 
.~ 
- 


adapted to match the host microcomputer hardware environment. Cold start initiali- 
ration of VO porn and similar h a i o n s can also be performed m the CPMLDR-BIOS 
module during the th~rd stage of cold start. 


In the banked version of CP/M 3, these first three stages of the cold boot procedure 


arc 
with Bank 0 in context. The BIOS Cold Start funelon switches in 
Bank 1 before proceeding to stage four. 
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- 
The fourth and final stage in the cold stan procedure is performed by the BlOS 


Cold Stan function, Function 0. The envy point to this function is located at 
BIOS-basc as dcsuibed in Section 1.4. The BlOS Cold Start function begins by 
- 
performing any remaining hardware initialization, m d initializing P a g Zcro. To 
initialize Page Zero, the BIOS Cold Stan function places a jump to BIOS-base + 3, 
the BlOS Warm Stan entry point, at location OOOOH, and a jump to BDOS_bax+ 6, 
the BDOS entry pomt, at locarlon OOOJH in mcmory. 
- 


The BlOS Cold Stan function completes the fourth stage by loading the CCP into 
the TPA region of memory and passing control to it. The CCP can be loadcd from 
one of two locations. If there is sufficient space in the system tracks for the CCP, it 
- 
is usually loaded from there. If there is not enough space in the system tracks, the 
BlOS Cold Stan function can mad the CCP h.om the file CCP.COM. 
- 
On some banked systems, the CCP is also copied to an alternate bank, so that 
warm stan operations can copy the CCP into the TPA from mcmory. This speeds up 
the system warm stan operation, and makes it possible to warm stan the system 
- 
withour having to access a system disk. 


When the CCP gains conml, rt displays a prompt that references the default disk. 
- 
If a PROFILE.SUB subrmr file is present on the default drive, the CCP cxmrtes this 
submit file before prompting the user for a command. 


At this point, the cold stan procedure is complete. Note that the uscr number is 
- 
set to zero when CP/M 3 is cold started. However, the PROFILE submit file can set 
the user number to another value if thts is dcnrablc. 


- 
The cold stan produre a designed so that the system tracks need to be initialired 


only once. This is accomplished because the system track routines ere independent of 
the configured memory sire of the CP/M 3 systcm. The Cold Boot Loader loads 
CPMLDR into a constant location in memory. This loution is chosen when the 
- 
system is configured. However, CPMLDR locates the BDOS and BlOS system corn- 
poncnn in mcmory as specified by the CPM3.SYS file. The CCP always executes at 
location lOOH in the TPA. Thus, CP/M 3 allows the uscr m generate a new syatcm 
- 
with GENCPM, and then run it without havlng to update the system track of the 
system disk. 


- 
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1.6.2 CCP Opaation 
- 


The Console Command Processor provides the user access to CP/M 3 facilities 


when transient programs are not running. It also reads the user's command lines, 
differentiates bcnveen built-in commands and transient commands, and executes the - 
commands accordingly. 


This section describes the responsibilities and capabilities of the CCP in some 


dead. The section beeins with a dcscriotian of the CCP's activities when it first - 


receives control from the Cold Start nrocedure. The smon contlnucs with a eeneral 
dlrcvrr~on of budt mn commands, and concluder wlth a .tep by step dcrrr~prlon of 
thc p-cdurc 
the CCP follows to execute the urrr'r commands 
- 


When the CCP gains control following a cold stnn procedure, it displays the 


system prompt at the console. This signifies that the CCP IS ready to execute a 
command. The system prompt displays the letter of the drive designated as the initial 
default drive during GENCPM operation. For example, if drive A was specified as 
the initial default drive, the CCP displays the following prompt: 


A > 


After displaying the system prompt, the CCP scans the directory of the default drive 
for the file PROFILE.SUB. If the file mists the CCP creates the command line 
SUBMlT PROFILE; otherwise the CCP rehs'the user's fint command line by mak- 
ing a BDOS Read Console Buffer function call (BDOS Function 10). 


The CCP accepts two different command forms. The simplest CCP command form 
changer the default drive. The following example illustrates a user changing the 
default drive from A to B. 


This command is one of rhe CCP's built-in commands. Built-in commands are pan 
of the CCP. They rcridc in memory while the CCP is active, and therefore can be 
executed without referencing a disk. 
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The second command form the CCP accepts is the standard CP/M command Ime. 


A standard CP/M command line consists of a mmmand keyword followed by an 
optional command tail. The command keyword and the command tail can be typed 
in any combination of upper-case and lower-case letters; the CCP converts all letters 
in the command line to upper-case. The following syntax defines the standard CP/M 
command line: 


where 
<command> 
= > <filespec> or 


<built-in> 


<command tail> 
= > (no command tail) or 


<filespec> or <frlcspec><dclirmru><frlespec> 


<built-in> 
=> one of the CCP built-in commands 


<dclimmr> 
= > one or more blanks or a tab or one of the 
following:" =,[I<> 
" 


d: 
= > CP/M 3 drive specificationI.(A"through"P" 


filmame 
=> 1 to 8 character filename 


- 
w 
= > 1 to 3 character filetype 


password 
=> 1 to 8 character password value 
- 
Fields enclosed in curly brackets are optional. If there ir no drive {d:) present in a file 
specification <filespec>, the default drive is assumed. If the type ficld {.typ) is omit- 
ted, a type field of all blanks is implied. Omitting the password ficld (;password) 
- 
implies a password of all blanks. When a command line is entered at the console, ~t 


Ir tcnn~nand by a return or line-feed keystroke. 


- 
Transient programs that run under CP/M 3 are not restricted to the above com- 
mand tail definition. However, the CCP only parsca command tails in this format for 
transient programs. Transient prozrams that define their command tails differently 
must performtheir own command;a~l parsing. 
- 
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The command fidd must identify either a built-in mmmand, a mnsient program, 
or a submtt file. For example, USER is the keyword that identifies the budt-m mm- 
mand that changes the current uscr number. The CP/M 3 CCP displays the user 
number in the system prompt when the user number is non-zero. The following 
example illustrates changing the user number from zero to IS. 


The following table summarizes the built-in commands. 


Table 1-1. CP/M 3 Built-in Commands 


Commnnd I 
Mednmg 


I 


displays a list of all filenames from a disk directory except those 
marked wlth the SYS attribute. 


1 DIRSYS 
displays a lilname Itst of those files m e a d with the X S 
amibutc in the d~mctory. 


l EMsE 


erases a filename from a disk d~rcctory and releases the storage 
occupied by the file. 


I RENAME 
renames a file. 
I 


TYPE 
display. the contents of an ASCII character file at your console 
output device. 


USER 
changes from one user number to another. 


Some budt-in commands have associated command files which expand upon the 


opttons provided by the built-in command. If the CCP reads a command line and 
discovers the built-in command does not suppon the options requested m the com- 
mand line, the CCP loads the built-in function's corresponding command file to 
perform the mmmand. The DIR command IS an example of this type of command. 
S~mple DIR commands are supported by the DIR built-in directly. More complex 
requests arc handled by the DIP..COM utility. 
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- All command keywords that do not identify built-in mmmandr identify either a 
transient program file or a submit file. If the CCP identifies a mmmand keyword as 
a transient program, the transient program file is loaded into the TF'A from drsk and 
executed. If rr recognizes a submit file, the CCP reconstructs the command line rnto 
- the following form: 


SUBMIT <command> <command tail> 
- 


and anempus to load and cxccurc rhc SUBMIT unliry. Thus, the orlg~nal command 
fic!d hrcomn the first command tall ficld of the SUBMIT mmmand. Srmon 1.6.5 
docrtkr the rxccunon of (:P M 3's SLIRMIT unltrv. The ~rocedure thc CCP fallowr 
- 
. 
. 
to parse a standard command hnc and execute built-in and transient commands is 
described as follows: 
- 
1. The CCP parses the command line to pick up the command field. 
2. If the command field is not preadcd by a drive specification, or followed by 
a filetype or password ficld, the CCP checks to see if the mmmand is a CCP 
- 
built-in function. If the command is a built-m command, and the CCP can 
support the options specified in the mmmand tail, the CCP executes the 
command. Othernix, the CCP goes on to step 3. 


3. At this point the CCP assumes the mmmand field references a command file 
or submit file on disk. If the optional filetype ficld is omitted from the mm- 
mand, the CCP usually assumes the mmmand field references a file of type 
- 
COM. For wample, if the command field is PIP, the CCP attempts to open 
the file PIP.COM. 
Optionally, the CP/M 3 utility SETDEF can specify that a filetype of SUB 
- 
also be consrded when the command filetype field is omitted. %en 
thls 


automatic submit option is m effect, the CCP ammpts to open the command 
with a filctypc of COM. If the COM file cannot be found, the CCP mpeaa 
the m e n aoeration with a filmoc of SUB. As an alternative. the order of 
. 
. 
, 
~ 
-. .. 
- 
open opcrarlons can he rcverrrd ro that the CCP anemptr to open wtrh a 
filrtypc of SUR first. In ctthcr care. the file rha~ s found on dirk firs drrrr- 
mlnn the filrwpr field that IS ulrlmalrly arsooatrd wnth the command. 
- 
If thc filctypc ficld Br pmmr ~n the command, II must equal COM, SUR or 
PRL A PRL file I? a Pagc Relocarahlc file urcd m Dtgral Kncarrh'r muln- 
user opcrarlng system, hlP M" Under CP M 3, the CCP handler PRL files 
- 
exactly like COM files. 
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If thc command field s pmfcdcd by a dnve spcaficaaon (d t, the CCP a m p a 
to opm the command or rubm~r file on the rpcclfied dnve. Orhcw~,r, rhc - 


CCP ancmprr to open rhc file on rhc drlvcr rpectficd ~n the drlvr cham. 


The dive chain s@es 
up m four d i v a that are m be mfemccd in sequence 


for CCP open operatlonr of command and submit files. If an open operation - 


is unsuccessful on a drive in the drivc chain because the file cannot be found, 
the CCP revean the oven overation on the next drive in the chain. ?his 
sequence oiopen oper&ons is repeated until the file is found, or the drive - 
chain is exhausted. The drivc chain contains the m r m t default drive as its 
only drive unless the uscr modrfies the drive chain with the CP/M 3 SETDEF 
utility. 
F 


When the current uscr number is non-zero, all open requests that fail because 
the file cannot be found, attempt to locate the command file under user zero. 
If the file exists under user zero with the system attribute set, the file is - 
opened from user zero. This search for a file under user zero a made by the 
BDOS Open File function. Thus, the user zero open attempt is made before 
advancing to the next drive in the search chain. 
- 


Whm automatic submit is in cffm, the CCP attempts to open with the first 
filetype, SUB or COM, on all drives in the search chain before trying the 
second filetype. 
- - 


In the banked system, if r password specified in the command field does not 
match the password of a file on a disk protected in Read mode, the CCP file 
open opcratlon is terminated with a password error. 
- 


If the CCP does not find the command or submit file, it echoes the command 
line followed by a question mark to the console. If it finds a command file 
wrth a filetype of COM or PRL, the CCP proceeds to step 4. If a finds a 
submit file, a reconstructs the mmmand hnc as described above, and repeats - 


step 3 for the command, SUBMIT.COM. 
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- 
4. When the CCP successfully opms the command file, it initializes the lollow- 


ing Page Zem fields for access by the loaded transimt program: 
OOJOH : Drive that the command file was loaded from 
- 
0051H : Password addms of fint file in command tail 
0053H : Password length of first file in command tail 
0054H : Password address of second filc in command tail 
0056H : Password length of second file m command tail 
- 
OOSCH : Parred FCB for first file m command tail 
006CH : Paned FCB for second file in command tail 
0080H : Command tall preceded by command tail length 
- 
Page Zero initialization is covered in more detail in Section 2.4. 
5. At this point, the CCP calls the LOADER modulc m load the command file 


into the TPA. The LOADER module terminates the load owration if a read 
- 
error occurs, or if the available W A space is not large en&& 
to contain the 


filc. If no RSXs are resident in memory, the available WA space is deter- 
mined bv the addreas LOADER base because the LOADER cannot load over 
ttself. &wise, 
the maximum TPA address LS dewmined by the base addres 


of the lowest RSX in memory. 


6. Once the program is loaded, the LOADER modulc checks for a RSX header 
on the program. Programs wlth RSX headen are identified by a return 
instruction at location 100H. 
If an RSX header is present, the LOADER relocates all RSXs attached to the 
end of the program, to the tap of the TPA region of memory under the 
LOADER module, or any other RSXs that arc already mident It also updares 
the address in location 0006H of Page Zero to addms the lowest RSX in 
memory. Finally, the LOADER discards the RSX hcadrr and relocates the 
program file down one page in memory so that the first executable mstruc- 
tlon resides at 100H. 


7. A 
h 
initializing Page Zero, the LOADER module sets up a 32-byte stack 
with the rerum address set to location OOOOH of Page Zero and lumps m 
location 100H. At this point, du loaded transimt pmgram beginr urntion. 
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When a transient program terminam execution, the BIOS warm start routine 
reloads the CCP into memory. When the CCP receives control, it tests to see if RSXs 
are resident in memory. If not, it relocates the LOADER module below the BDOS 
module at the top of the TF'A regton of mcmory. Otherwise, it skips this step because 
the LOADER module la already resident. The CCP execuuon cycle then repeats. 


Unlike earlier versions of CP/M, the CCP docs not mn the disk system at warm 
start. However, the CCP does reset the disk system if a CTRL-C is typed at the 
prompt. 


1.6.3 Transient Pmgram Opcmtiom 


A transient program is one that the CCP loads inm the TPA region of mcmory 


and executes. As the name transient implies, transient programs am not system resi- 
dent. The CCP must load a transient program tnto mcmory every time the program 
n to be executed. For example, the utilities PIP and RMAC" that are sh~pped with 
CP/M 3 execute as transient programs; programs such as word processing and 
accounting packages distributed by epplicatlonr vendors also execute as transient 
programs under CP/M 3. 


Section 1.6.2 describes how the CCP prepared the CPIM 3 environment for the 
execution of a transient program. To summarile, the CCP initializes Page Zero to 
mntain parsed command-li& fields and sen up a 32-byte stack before bmping to 
location OlOOH to pass mntrol to the transient program. In addition, the CCP might 
alx, load RSXs anached to the command file into memow for access hv the transient 
program. 


Generally, an executing transient program mmmunicates wrth the operating sys- 
tem only through BDOS function calls. Transient programs make BDOS function 
calls by loading the CPU registers with the appropriate entry parameters and callmg 
location OOOSH in Page Zero. 


Transient programs can use BDOS Function SO, Call BIOS, m access BIOS entry 
points. This is the preferred method for accessing the BIOS; however, for compatibil- 
iry with earlier releases of CPIM, transient programs can alw make duect BIOS calls 
for console and list VO by usmg the jump instruction at location OOOOH in Page 
Zero. But, to simplify portability, use direct BIOS calls only where the primitive level 
of funaionality provided by the BIOS functions is absolutely required. For example, 
a dlsk formatting program must bypass CP/M's disk organization to do ~ t s 
job, and 


therefore is justified in making direa BIOS calls. Note however, that disk formanlng 
programs ate rarely portable. 
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A transient program can terminate wecution m one of three ways: by jumping m 
location OOOOH, by making a BDOS System Reset call, or by making a BDOS Chain 
To Program call. The first nvo methods are equivalent; they pass control to the BIOS 
warm start entry point, which then loads the CCP into the TPA, and the CCP 
prompts for the n a t command. 


We Chain to Program call allows a transient program to specify the next com- 
mand to be a m r e d before it terminates as own aecution. A Program Chain call 
aemtes a standard warm boot sequmce, but passes the command specified by the 
terminating program to the CCP in such a way that the CCP e x e m s the specified 
mmmand tnstcad of prompting the console for the next command. 


Tranrrmr programs can also m a Program Return Code bcforc trmlnanng by 


maklng a RDOS Funcnon 108 call, W S r r Program Rcrurn Code. The CCP ~n~rxal- 
rzcn thc Proflam Rcrurn Codc ro zero, rucccrohl. when hr load, a translent pmgnm, 
unless the program is loaded as the result of a program chain. Therefore, a transient 
program that terminates successfully can use the Program Return Code to pass a 
value m a chained pmgmm. If the program terminates as the result of a BDOS fatal 
error, or a CTRLC entered at the console, the BDOS sets the murn code m an 
unsuccessful value. All other types of program termination leave the return code at 
its curmt value. 


The CCP has 1 conditional command facility that uses the Program Return Code. 
If a command line submitted to the CCP by the SUBMR utility begins with a colon, 
the CCP skips execution of the command if the previous command set an unsucccss- 
ful Program Return Code. In the following example, the SUBMIT utiliry smds a 
command sequence m the CCP: 
- 


A>SULIUIT S U B F I L E 
fl>COUPUTE RESULTS.DOT 
A > : REPORT RESUL TS.0OT 
- 


The CCP does not a m t c the REPORT command rf the COMPUTE command sets 
an unsucmsful Program Return Code. 
- 
1.6.4 Reridmt System h r i o n Operation 


This section gives a general overview of RSX use, then describes how RSXs are 
- 
loaded, defines the RSX file structure, and tells how the LOADER module uses the 
RSX prefix and flags m manage RSX activity. 
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A Rcsldent System Extension (RSX) is a special type of program that can be 
attached to the operating system to modify or extend the functionality of the BDOS. 
RSX modules intercept BDOS functions and either perform them, translate them into 
other BDOS functions, or pass them through untouched. The BDOS wecutes "on- 
intercepted functions in the standard manner. 


A transient program can also use BDOS Function 60, Call Resident System Enen- 


sion, to call an RSX for spcclal functions. Function 60 is a general purpose funcuon 
that allows customized interfaces between programs and RSXs. 


Two wampla of RSX applications arc the GET utility and the LOADER module. 
The GET.COM command file has an anached RSX, GET.RSX, which intercepts all 
console input calls and returns characters from the file specified in the GET command 
line. The LOADER module is another example of an RSX, but it is special because 
it suppons Funaton 59, Load Overlay. It 1s always resident in memory whcn other 
RSXs arc active. 


RSXs are loaded into memory at program load nmc. As described in Section 1.6.2, 
after the CCP locates a command file, it calls the LOADER module to load the 
program into the TPA. The LOADER loads the transient program inm memory 
along with any attached RSXr. Subsequently, the loader relocates each attached RSX 
to the top of the TPA and adjusts the TPA sire by changing the lump at locatton 
0005H ~n Page Zero to point to the RSX. Wlcn RSX modules reside in memory, the 
LOADER module resldn directly below the BDOS, and the RSX modules stack 
downward from it. 


Thr order m which the R\X modules arc rrackcd affcnr the order ~n w h ~ h 
they 


Intercept RDOS calls A mure rcccntly \racked RSX har prcccdcncr over an oldcr 
R\X Thus, tf two RSXs tn mcmory ~ntcrccpt rhc 5amc BDOS funcnon, the more 
recently loaded RSX handles the function 


The CP/M 3 utlliry GENCOM attaches RSX modules to program files. Program 


files with attached RSXs have a special one page header that the LOADER recognizes 
whcn it loads the command file. GENCOM can also attach one or more RSXs to a 
null command file so that the CCP can load RSXs without having to execute a 
transient program. In th~s case, the command file consists of the RSX header fol- 
lowed by the RSXE. 


RSX modules are Page Relocatable, PRL, files with the file type RSX. RSX files 
must be page relocatable because their execution address is determined dynamically 
by the LOADER module at lord time. RSX files have the follow~ng format: 


DIGITAL RESEARCH'" 


1-24 
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END OF FILE 


RSX PREFIX 


OlOOH 


256 BYTE PRL HEADER 


0000H. 
6" ce' 


F i e 1-8. RSX File Format 


RSX files begin with a one page PRL header that specifies the total sirc of the RSX 


prefix and code sections. The PRL b r map is a string of bits ldcnufying those bytes 
m the RSX prefm and code sections that require relocation. The PRL format is 
dsaibed in detail in Appendix B. Note that the PRL header and ba map are removed 
when an RSX is loaded into memory. They arc only used by the LOADER module 
to load the RSX. 


The RSX prefix is a standard data structure that the LOADER module uses to 


manage RSXs (sa Section 4.4). lndudcd in this data structure are jump instructions 
to the previous and n u t RSX ~n memory, and two flags. The LOADER module 
initializes and updates these lump instructions to maintain the link from location 6 
of Page Zero to the BDOS entry point. The RSX flags are the Remove flag and the 
Nonbanked flag. The Remove flag controls RSX removal from memory. The CCP 
tests this flag to determine whether or not it should remove the RSX from memory 
at system warm start. The nonbanked flag identifies RSXs that are loaded only m 
nonbanked CP/M 3 systems. For example, the CP/M 3 RSX, DIRLBL.RSX, is a 
nonbank~d RSX. It provides BDOS Function 100, Set Directory Label, support for 
nonbankcd systems only. Banked systems support this function in the BDOS. 


The RSX code section contains the main body of the RSX. This sectron always 


begins with code to intercept the BDOS function that is s u p p o d by the RSX. 
Nonrntercepted functions are passed to the next RSX m memory. This section u n 
also indude initialization and termination mde that transient programs can call wlth 
BDOS Function 60. 
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When the SUBMIT utility besins armtion, it opens and reads the file specified by 


<filrspcc> and rrcater a temporary wbmtt file of type IS$ on the rystcm's tempo- 
rary file dnvc. GENCPM ~nrrlal~zrr 
the rrmpurary file drwe to rhr CCP'v current 


default drwc 'Ihc SEmFF urnl~ry can rn the temporary file drwc to a rpcafic dnvc. 
As it aeater the temporary file, s ~ M I T 
performs ;he 
subtimtiins requested 
by the <parameters> rubfield of the SUBMIT command line. See the CP/M Plus 
(CP/M Version 3) Operating System User's Guide for a detailed description of this 
process. 


After SUBMIT creates the temporary submit file, its operation is similar to that of 
the GET utility described in Section 1.6.4. The SUBMIT command filc also has an 
anacbed RSX that performs console input rcdtrect~on from a filc. However, the 
SUBMIT RSX expands upon the simpler facilities provided by the GET RSX. Com- 
mand ltncr ~n a ruhm~r file can bc marked to bnd~carc whcrhcr they arc program or 
CCP mput. kurthcrmorc, ! f a propram exhaurrr all ar program Input, the next \UB- 
Ml'1 command nr a CCP command, rhc SURMIT R\X trmpurarlly rrvcnr to sunrulc 
input. Red~rened lnput from the submit filc resumes when the program terminates. 


Because CP/M 3's 
submit facility is implemented with RSXs, submit files can be 
nested. That is, a submlt filc can contain additional SUBMIT or GET commands. 
S~mtlarlv. a GET command can s~ecihr a file that contains GET or SUBMIT com- 
. ' 


mands. For wamolc. when a SUBMIT command is encountemd in a submit file. a 
. . 


ncw \L8BMI'I' RSX s created bcluw rhc currcnt KSX. The new R\X handle3 conrolc 
input unr~l nr rcadr end-of-file on Its rcmporary ruhmtr file. At thi, punnr, control 
- 
men5 to thc pmvluu, SUBMIT RSX. 


- 
1.7 System Control Block 


The System Control Block, SCB, is a 100 byte CP/M 3 data structure that resides 
in the BDOS system component. The SCB contains internal BDOS flags and data, 
- 
CCP flags and data, and other system infomation such as console charactcr~stics and 
the current date and time. The BDOS. BIOS. CCP svstem comoonents as well as 
~~~ -. 


CP/M 3 utilities and RSXI reference SdB fields. B D O ~ 
Fundon '49, GeUSet System 
- 
Col~trol Block, provides access to the SCB fields for transient programs, RSXs, and 
the CCP. 


- 


Et DIGITAL RESEARCH" 
1-27 
- 
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Howcucr, use caution when you a-as 
the SCB through Function 49 for two 


reasons. First, the SCB is a CP/M 3 data structure. Digital Research's multi-user 
operating system, MPIM, does not support BDOS Function 49. Programs that access 
the SCB can run only on CP/M 3. Secondly, the SCB contains crltlcal system param- 
eters that reflect the currat state of the operating system. If a program modifies these 
parameters dlegally, the operating system might crash. However, for application writ- 
ers who are writ~ng system-oncnted applicat~onr, access to the SCB variables might 
prove valuable. 


For example, the CCP default drive and current user number am maintained in the 


System Control Block. Thlr information is displayed in the system prompt. If a 
transient program changes the currat disk or user number by making an explicit 
BDOS call, the System Connol Block valuer are not changed. They continue to reflect 
the state of the system when the transient program was loaded. For compatibility 
with CP/M Version 2, the currat disk and user number are also ma~ntained in 
location 0004H of Page Zero. The high-order nibble contains the user number, and 
the lowarder nibble contains the drive. 


Refer m the description of BDOS Function 49 in Section 2.5 for more infomatlon 


on the System Control Block. The SCB fields arc also discussed m Append~x A. 


End ofSection 1 


- 
Section 2 
The BDOS System Interface 


Th~s section describes the operating system services available m a transient pro- 
gram through the BDOS modulc of CP/M 3. The section begins by defining haw a 
- 
transient m o m m calls BDOS functions. then discusses serial UO for mnsole. list and 
. - 


auxiliary devices, the file system, and Page Zero mitialization. 
- 2.1 BDOS Calling Conventions 


CP/M 3 uses a standard convention for BDOS function calls. On entry to the 
- 
BDOS, register C contains the BDOS function number, and register pair DE mntains 
a byte or word value or an information address. BDOS functions return single-byte 
values in register A, and doublc-byte values in regrster pair HL. In addition, they 
- 
return wlth regrrter A equal to L, and regster H equal to B. If a transient program 
makes a BDOS call to a nonsupporvd function number in the range of 0 to 127, the 
BDOS returns with register pair HL set to OFFFFH. For compatibility with MPIM, 
- 
the BDOS returns wlth regstcr pair HL set to OOOOH on nonsupported function 
numbers m the range of 128 to 255. Note that CP/M 2 returns with HL set to zero 
on all invalid funct~on calls. CP/M 3's register passing conventions for BDOS func- 
- 
tion calls are consistent with the conventions used by the Intel PUM systems pro- 
gramming language. 


When a transient omcram makes a BDOS function call. the BDOS does not restore 
. - 
- 
regsten to their entry values before murning to the calling program. Ihe responsi- 
bility far saving and mmnng any critical register valuer rests wth the calling program. 


- 
When the CCP laads a uansicnt program, the LOADER module sets the stack 


polntcr to a 16 level stack, and then pushes the address OOOOH onto the stack. ?bus, 
an immediate return to the system is equivalent to a jump to OOOOH. However, most 
transient programs set up their own stack, and terminate execution by making a 
- 
BDOS System Resn call (Function 0) or by jumping to location 0000H. 
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The followtng example illustrates how a transtent program calls a BDOS function. 
This program reads characters continuously unul it encounters an asterisk. Then it - 


terminates execution by returning to the system. 


bdos 
esu 
0 0 0 5 h 
;BOOS e n t r r ~ 
o 
~ 
n 
t 
i n P a l e Z e r o 
- 


o o n i n 
e4u 
1 
;EDUS c o n s o l e i n p u t f u n c t l o n 


o r 9 
lOOh 
;Base o f T r a n s l e n t Prolran Area 
- 


nrxtc: 
mui 
c e c o n i n 


c a l l 
b d o r 
: R e t u r n c h a r a c t e r i n A 


c 
~ 
i 
'i' 
;End o f ~ r o e r r s l n 9 ? 


J n r 
n e ~ t c 
;Loop i f n o t 
- 


r e t 
; T e r m i n a t e ~ r o l r a n 


end 
- 


2.2 BDOS Serial Device W 0 
- 


Under CP/M 3, serial device U0 is simply input to and output from simple devices 
such as consoles, hne pnntcrs, and communicat~ons devices. These physical devices 
can be ass~gned the logical device names defined below: 
- 


CONIN: 
logical console input device 


CONOUT: 
logical console output device 
AUXIN: 
logccal auxiliary tnput device 
AUXOUT: 
logical auxiliary output dw~ce 


LST: 
logical list output dwlce 


If your system supports the BlOS DEWBL function, the CP/M 3 DEVICE utility - 


can display and change the assignment of logical devlcer to physical devlccs. DEVICE 
can also display the names and attributes of physical devices supported on your 
system. If your system does not support the DEVIBL entry point, then the logical to - 
physical device arstgnmcnts arc fixed by the BIOS. 


In general, BDOS wrlal VO functions read and write an individual ASCII charac- - 


tcr, or character string to and from these devices, or test the device's ready status. 
For these BDOS funct~onr, a string of characters is defined as zero to N characters 
terminated by a delimiter. A block of characters is defined as zero to N characters 
where N is specified by a word count field. The maxlmum value of N in both cases - 


is limited only by avallablc memory. The following list ~ummarines BDOS serial 
device 110 functions. 
- 
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Read a character from CONIN: 
Read a character buffer from CONIN: 
Write a character to CONOUT: 
Wr~te a string of characters to CONOUT: 
Write a block of characters to CONOW: 
Read a character from AUXIN: 
Wrtte a character to AUXOW: 
Write a character to LST: 
Wnte a block of characters to LST: 
Interrogate CONIN:, AUXIN:, AUXOW: ready 


CP/M 3 cannot run unless CONIN: and CONOUT: are assigned to a physical 
console. The rcmarnlng logical devlccs can remain unasngned. If a logical output 
device is not assigned to a physical device, an output BDOS call to the logical device 
performs no actlon. If a logical input device is not assigned to a physical devrce, an 
input BDOS call to the logcal device typically returns a CTRL-Z (IAH), w h ~ h 
indicates endaf-file. Note that these actions depend on your system's BlOS 
implementation. 


2.2.1 BDOS Console YO 


Because a transient program's man interaction with its user is thmugh the mnsole, 


the BDOS supporn many console UO functions. Console UO functions can be divided 
)"to four categorlcr barnc conrolc 1 0 , dtrm mnrolc 1 0 , buffered ~0nrok Input. 
and rpcc~al conrole funsttons Urmg the bas~c mnrolc LO funcnons, programs can 
access the mnwlc dcvlrr for ~tmplc Input and output T h e bavc console 1 0 func- 


IlO"l I r e 


1. Console Input - Inputs a single character 
2. Console Output- Outputs a single character 
9. Prlnt Smne 
- Outouts a stnne of characters 
- 
11. Console Status - Signals if a character is ready for input 


111. Print Block 
- Outputs a block of characters 


The input function echoes the character to the console so that the user can identlh/ 
- 
the typed charactcr. The output functions expand tabs ~n columns of eight characters. 
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The basic UO functions also monitor the console to stop and stan console output 
scroll at the user's request. To provide this support, the console output funct~ons - 


make internal status checks for an input character before writing a character to the 
output device. The console Input and console status functions also check the input 
character. If the user types a CTRL-S, these funct~ons make an addittonal BIOS - 
console input call. Thls input call suspends execution until a character a typed. If the 
typed character is not a CTRL-Q, an additional BIOS console tnput call is made. 
Execution and console scrolling resume when the user types a CTRL-Q. 
- 


When the BDOS is suspended because of a w e d CTRL-S, it scans input for three 


spec!al characters: CTRL-Q, CTRL-C, and CTRL-P. If the user types any other 
character, the BDOS echoes a bell character, CTRL-G, m the console, discards the - 


lnput character, and continues the scan. If the user types a CTRL-C, the BDOS 
executes a warm start which terminates the calling program. If the user types a 
CTRL-P, the BDOS toggles the prlntcr echo swach. The pr~nter echo swltch controls - 
whether console output is automatically echoed to the list device, LST:. The BDOS 
signals when a Nrns on printer echo by sending a bell character to the console. 
- 


1\11 bavc con\ulc LO functtons dmiacd any CTR1.-Q or CTRl -P character that IS 


nor preceded hy a CTRI.-S ;hara;rcr. nu,, 
BOOS funrt~un 1 cannot read a ( TRI - 


S. C'1KL.Q or CI'RL.P character. Furthermore, rhcrc characters are nnvartblc to the 
console status function. 
- 


The second category of console UO is direct console UO. BDOS function 6 can 
provide direct console UO in situations where unadorned console VO is requrred. - 
Funmon 6 actually cons~sts of weml sub-functions that support direct console input, 
output, and status checks. ?he BDOS does not filter out specgal characters during 
dlrect console UO. The direct output sub-haion doer nor expand tabs, and the - 
direct input sub-function does not echo typed characters to the console. 


The third cateeorv of console UO accents edited ~nout from the console. The onlv 


funonon ~n rh~v category, Functlon 10. Read Buffer Input, mads an mput line from a - 
buffer and rrcognlzr, ccrtaln control charactem that cdlr the mput A5 an opt~on, thc 
ltnc to bc cdtrrd can be rnrtralrrcd by the call~ng program 
- 


In the nonbanked venion of CP/M 3, edkting within the buffer is restricted to the 
last character on the Ime. That is, to edit a character embedded in the line, the user 
must delete all characters that follow the erroneous character, correct the error, and 
then retype the remainder of the line. The banked vcnion of CP/M 3 ruppons 
* 


complctc line editing in which characten cm be deleted and inserted anywhere in the 
line. In addition, the banked vcnion can also recall the previously entered line. 
- 
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- 
Function 10 also filters input for certain control characters. If the user types a 
CTRL-C as the first character in the line, Funcuon 10 terminates the calling program 
by branching to thc BIOS warm start cntry point. A CTRL-C 
m any other posltion 
- is simply echoed at the console. Function 10 also watches for a CTRL-P keystroke, 


and if it finds one at any positlon in the command line, it toggles the printer echo 
switch. Funcuon 10 does not filter CTRL-S and CTRL-Q characters, but accepts 
them as normal input. In general, all control characters that Function 10 does not 
- recognize as editing control charanen, it accepts as input characters. Function 10 
identifies a control character with a leading caret, ', when it echoes the control 
character to the console. Thus, CTRL-C appears as "C m a Function 10 command 
- line on the screen. 


The final category of console UO functions indudes special functions that modify 
the behavior of other console functions. These funcuons are: 
- 


109. GcdSet Console Mode 
110. GetISet Output Delimiter 
- 


Function 110 can get or set the current delimiter for Function 9, Print String. The 
delimiter 1s $, when a transient program begins orecutlon. Funcrion 109 gets or sets 
- 
a 16-bit system variable called the Console Mode. The following list describes the 
bits of the Console Mode variable and their functions: 


bit 0 : If this bit is set, Function 11 returns true only if a CTRL-C is typed at the 
- 
con,olr Progmm~ that make rcpcarrd console status calls ro rest ~f cxrcurnon 
vhould be mtcrruprrd, can ,cr th,r br to lnrrrrupt on CIRL-C only Thr 
CCP DIR and TYPt butlr ~n commrndr run 10 rh15 modc 
- 
bit 1 : Setting this bit disables stop and start scroll support for the basic console 
UO functions, which comprise the first category of functions described in 
- 
this section. When this bit is set, Function 1 reads CTRL-S, CTRL-Q, and 
a - P , and Function 11 returns uue d the user types these characters. Use 
this mode in situations where raw console inout and edited oumur is needed. 
Whtlc ,n r h n modc, you can usr Funcr~on 6 for lnpur and Input status, and 
- 
tuncttonr 1, 9, and 111 for output ulthour rhc porr~btllty of the output 
funct~on5 lnrerceptmng mpur CTRL-S, CTRl Q, ur CTRL-P charancr~ 


- 
bit 2 : Setting this bit disables tab expansion and printer echo support for Functions 
2, 9, and 111. Use this mode when "on-ebtcd output is required. 
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bit 3 : Thls bit disables all CTRL-C intercept action in the BDOS. This mode is 
useful for programs that must control their own terminatton. 


bits 8 and 9 : The BDOS docs not use thae bm, bur reserves them for the CP/M 3 
GET RSX that performs console input red!rection from a file. With one 
exceptxon, these bltr determine how the GET RSX responds to a program 
console status request (Function 6, Function 11, or d~rect BIOS). 


bit 8 = 0, bit 9 = 0 - conditional status 
ba 8 = 0, bit 9 = 1 - false status 
bit 8 = 1, bit 9 = 0 - true status 
bit 8 = 1, bit 9 = 1 - do not perform redirection 


In conditional status mode, GET responds false to all staNs requests except for a 


status call preceded immediately by another status call. On the second call, GET 
responds wtth a true result. Thus, a program that spins on starus to wait for a 
character in signaled that a character is ready on the scmnd call. In addition, a 
program that make status calls periodically to rcc if the user wants to stop is not 
signaled. 


Whm a transtmt program bcpnn exemuon, the Console Mode bcr are normally 


rcr to rcro. Howcvcr, the CP .U 3 ur~lrty GENC0.M can anach an RSX header m a 
COM file ro that when n 1s loaded. the console mode bntr arc u r dlfferently Thrr 
feature allows you to modify a program's console WO behavior without having to 
change the program. 


The BDOS supporn single character output functions for the logical devices LST: 
and AUXOUT:, an input function for AUXIN:, and status functions for AUXIN: 
and AUXOm:. A block output function is also s u p p o d for the LST: device. 
Unlike the console WO funcuons, the BDOS does not intercept mntral characters or 
expand tabs for these functions. Note that AUXIN: and AUXOUT: replace the 
READER and PUNCH devices supported by earlier versions of CP/M. 
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- 2.3 BDOS File System 


Transimt programs depend on the BDOS file sysnm to mare, update, and main- 
- 
rain disk files. This smion describes the capabilities of the BDOS file system in detail. 
You must understand the general features of CP/M 3 described in Section 1 before 
you can ur the detail presented in this secrion. 
- 
The remaining introductory paragraphs ddrne the four categories of BDOS filc 
functions. This is followed by a review of file naming conventions and disk and file 
organization. The section then describes the data strumre used by the BDOS filc, 
- 
and directory onented functions: the File Control Block (FCB). 
Subsequent discus- 


slons cover file attributes, user numbers, directory labels and extended File Control 
Blocks (XFCBs), passwords, date and time stamping, blocking and dcblockmg, multi- 
- xnor UO, disk reset and removable media, byte counts, and error handling. These 
topics are closely related to rhe BDOS file system. You must he famlhar with the 
contents of Section 2 before anempting to use the BDOS functions described individ- 
ually in Section 3. 


The BDOS file systcm supporn four categories of functions: file access functions, 
directory functions, &we related functions, and misrrllaneous functions. The file 
access catcgory induda functions to mate a file, open an existing file, and close a 
file. Both the make and open functions activate the file for subsequent access by 
BDOS filc access functions. The BDOS read and write functions are file access func- 
tions that operate elther sequentially or randomly by record position. They transfer 
data in units of 128 bytes, which is the basic record size of the file system. The close 
function makes any necessary updates to the directory to permanently record the 
status of an activated file. 
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BDOS directory functions operate on existing file entries in a drive's directory. - 


Th~r category indudes functions to search for one or mare files, delete one or mare 
files, truncate a file, rename a file, set file attributes, assign a pasword to a file, and 
compute the sire of a file. The search and delete hurctions are the only BDOS func- 
ttons that support ambiguous file references. All other directory and file related func- ' 


tions require a specific file reference. 


The BDOS drive-related category indudes functions that select the default drive, - 


compute a drive's free space, interrogate drive status, and assign a dmctory label to 
a drive. A drive's directory label controls whether or not CP/M 3 enforces file pass- 
word protection, or stamps files w ~ t h the date and time. Note that the nonbanked - 
version of CP/M 3 docs not support file passwords. 


We miscellaneous category indudes functions to set the current DMA address, 
access and update the current user number, cham to a new program, and flush - 
internal block~ngideblocking buffers. Also included are functions that set the BDOS 
multi-sector count, and the BDOS error mode. The BDOS multi-sector count deter- 
mines the number of 128-bye records to be processed by BDOS read and write - 
functions. It can range from 1 to 128. The BDOS error mode determines how the 
BDOS file system handla certam dasscs of errors. 


Also included in the midlaneous category are functions that call the BIOS M y , ' 


set a program return code, and parse filenames. If the LOADER RSX a resldent In 
memory, programs can also make a BDOS function call to load an overlay. Another 
m~scellaneous function accesses system variables in the System Control Block. 
- 
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The following list summarizes the opcrauons prformed by the BDOS file system: 


Disk System Reset 
Drive Selection 
File Creation 
File Open 
Ftle Close 
Directory Search 
File Delete 
File Rename 
Random or Sequential Read 
Random or Sequential Write 
Interrogate Selected Dish 
Set DMA Address 
SetReset File Attributes 
Reset Drive 
Set BDOS Multi-Soaor Counc 
Set BDOS Error Mode 
Get Disk Free Space 
Chain to Program 
Flush Buffen 
GetiSct System Control Block 
Call BIOS 
LoahOver~a~ 
Call RSX 
Truncate File 
Set Directory Label 
Cm File's Date Stamps and Password Mode 
Write File XFCB 
SedGet Date and Time 
Set Default Password 
Return CP/M 3 Serial Number 
GeriScr Program Return Code 
Parse Filename 


2.3.1 
File Naming Convmuonr 


Under CP/M 3, a file specification mnsisa of four pam: the drwe specifier, the 
filename field, the filetype field, and the file password field. The general format for a 
mmmand line file spec~fication is shown below: 
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The drivc specifier field specifies the drwe where the file 1s located. The filename and 
type fields ldenttfy the file. The password field specifies the password if a file is 
password protected. 


The drive, rype, and password fie16 are opoonal, and the delimiten :.; are required 
only when specifying their arsoc~ated field. The drive specifier can be assigned a letter 
from A to P where the actual drive letters supported on a given system are deter- 
mined by the BlOS implementation. When the drive lemr is not specified, the current 
default drive is assumed. 


The filename and password fields can contain one m eight non-delimiter charac- 
ters. The filetype field can contain one to three non-delimiter characters. All three 
fields are added with blanks, if necessary. Omitting the optional type or password 
fields implies a field specification of all blanks. 


The CCP calls BDOS Function 152, Parse Filename, to pane file specifications 
from a command line. Function 152 recognizes certain ASCII characters as valid 
delimit- 
when it parses a file from a command line. The valid delimlters are shown 
in Table 2-1. 


Table 2-1. Valid Filename Ddimiters 


ASCII 
HEX EQUIVALENT 
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Function 152 also exdudes all control characters from the file fields, and translates all 
lower-case letters to upper-case. 


Avoid using parentheses and the backslalash character, \, in the filename and filctype 


fields because they are commonly used delimiters. Use asterisk and question mark 
characters, . 
and ?, only to make an ambiguous file reference. W e n Function IS2 


encounten an 
in a filename or filetype field, it pads the remainder of the field with 


qucstlon marks. For uamplc, a filename of X'.' 
is parsed to X???????.???. 
The 


BDOS search and delete fundons treat a ? in the filename and type fields as follows: 
A ? in any position matches the corresponding field of any directory entry belongng 
to the current user number. Thus, a search operation for X???????.??? 
finds all the 
current user files on the directory beginning in X. Most other file related BDOS 
functions treat the presence of a ? in the filename or type field as an error. 


It is not mandatory to follow the file naming conventions of CP/M 3 when you 


mate or rename a file with BDOS functions. However, the conventions must be used 
if the file is to be a-wd 
from a command line. For example, the CCP cannot locate 
a command file in the directory rf its filename or type held contains a lower-easc 
lemr. 


As a general rule, the filnype field names the generic category of a pmcular file, 
while the filename distinguishes individual files in each category. Although they are 
gmerally arbitrary, the following list of filctypcs names some of the generic categories 
that have been estabhshed. 


ASM 
PRN 
HEX 
BAS 
MT 
COM 
PRL 
SPR 


Assembler Source 
PU 


Printer Listing 
REL 


H u Machine Code 
TEX 


Basic Source File 
BAK 


Intermebate File 
SYM 
Command File 
SSS 


Page Rclocatablc 
DAT 


Sys. Page Reloc. 
SYS 


PUI Source File 
Relocatable Module 
TEX Formatter Source 
ED Source Backup 
SID Symbol File 
Temporary File 
Data File 
System File 


2.3.2 
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The BDOS file system can support from one to sixteen logical drives. The maxi- 
mum file size supported on a drive is 32 megabytes. The maximum capacity of a 
drive is determined by the data block sire specified for the drive in the BIOS. The 
data block s t u 1s the basic unit in which the BDOS allocates disk space to files. 
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Table 2-2 displays the relationship between data block sine and drive capacity. - 


Table 2-2. Logical Drive Capacity 


D m 
Block Size 
I 
Maximum Drive Capacity 


256 Kilobytes 
64 Megabytes 
128 Megabytes 
256 Megabytes 
512 Megabytes 


Logical drives are divided into two repons: a dimtory area and a data area. The - 


dimtory area contains from one to sixteen blocks located at the beginning of the 
dnve. The actual number is set in the BIOS. This area contains enttier that define 
which files exist on the drive. The directory entries corresponding to a particular file 
define those data blocks in the drive's data area that belong to the file. These data - 


blocks contain the file's records. The directory area IS logically subdivided into six- 
teen independent directories ident~fied as user 0 through 15. Each independent direc- 
tory shares the actual directory area on the drive. However, a file's directory entries - 
cannot exist under more than one UMI numbec In general, only files bdonging m 
the cumnt user number are visible in the directory. 
- 


Each disk file consists of a set of up to 262,144 128-byte records. Each record in 
a file is identified by its position in the file. This pasirion a called the remrd'r random 
record number. If a file is created sequentially, the first record har a position of zero, 
while the last record has a position one less than the number of remrdr in the file. - 


Such a file can be read sequentlally in record position order beginning at record zero, 
or randomly by record por~tion. Conversely, if a file is created randomly, records are 
added to the file by specified position. A file created in this way is called sparse if - 
positions exist within the file where a record has not been written. 


The BDOS automatically allocates data blocks to a file to contain its records on 
the basis of the record positions con~umed. Thus, a sparse file that contains two - 


records, one at position zero, the other at position 262,143, consumcs only two data 
blacks in the data area. Sparse filer can only be created and accessed randomly, not 
sequentially. Note that m y data block allocated to a file is pmanenrly allocated to - 
the file until the file is deleted or truncated. These are the only mechanlams supported 
by the BDOS for releasing data blocks belonging to a file. 
- 
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- 
Source files under CP/M 3 are treated as a sequence of ASCII characters, where 
each line of the source file is followed by a carriage return line-feed sequence, ODH 
followed by OAH. Thus a single 128-hp record could contain several lines of source 
text. The end of an ASCII file is denoted by a m L - Z character, IAH, or a real end 
- of file, returned by the BDOS read opcrauon. CTRL-Z characters embedded wlthin 


machine code files such as COM files are rgnored. The actual end-of-file condition 
returned by the BDOS is used to terminate read operations. 
- 2.3.3 
File Control Block Ddinition 


We File Control Block, FCB, is a data structure that is m up and initialized by a 
- transient program, and then used by any BDOS file access and directory functions 
called by the transient program. Thus the FCB is an important channel for infoma- 
tion u c h a n ~ e between the BDOS and a transient program. Far example, when a 
- program op&r a file, and subsequently accesses it with BDOS mad and write record 
functions, the BDOS file system maintains the current file state and position withrn 
the ~romam's FCB. Some BDOS hnatona use certain fields in the FCB for invokiinz 
special options. Other BDOS hnctions use the FCB to return data to the calling 
- program. In additton, all BDOS random I/O functions specify the random record 
number with a 3-byte field at the m d of the FCB. 


When a transient oromam makc. a file access or direnorv BDOS function call. 
- 
, - 


mgntcr par DE must address an FCB T h e length of the FCR data area dcpcndr on 
the BDOS hnsnan For most hnn~onr, the rcqulred length to 33 bytcr For random 
1 0 funct~onr, thr Truncate Rlc funalon, and the Compute Fllc 4.c hnmon, the 
- FCB length must be 36 bytes. The FCB format is shown on the next page. 


- 
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where 


dr 
drive code (0 - 16) 
0 = > use default drive for file 
1 => auto d~sk sclea drive A, 
2 = > auto disk select drwe B, 


16=> auto disk select drive P. 


f l ... f8 
contain the filename in ASCII 
upper-are, with high bit = 0. 
fl', ..., f8' denote the high- 
order bit of these pontlons, 
and are file attribute bin. 


tl,t2,t3 
contain the filetype in ASCII 
upper-case, with high bit = 0. 
tl', t2', and 13' denote the 
high bit of there positions, 
and am file attribute bits. 
11' = 1 = > RcadIOnly file 
t2' = 1 = > System file 
13' = 1 => File has been archived 


ex 
conrams the current cxtcnr number, 
usuall) rcr ro 0 by the calling program, 
but can range 0 - 31 dunng file LO 


1 
reserved for internal system use 


s2 
merved for internal system use 


rc 
record count for extent "ex" 
taka on values from 0 - 255 
(values grcaer than 128 imply 
record count equals 128) 
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d0 ... dn 
filled-in by CP/M 3, reserved for 
system use 


cr 
cumnt record to read or write m 
a sequential file operation, normally 
set to zero by the calling program 
when a file is opened or created 


O , l 2 
optional random record number in the 
range 0-262,143 (0 - 3FFFFH). 
ro,rl,R constitute a 18 ba value 
with low bytc rO, mlddle byte rl, and 
high byte r2. 


For BDOS directory functions, the calling program must in~tialize bytes 0 through 


11 of che FCB before issuing the function call. The Set Directory Label and Write 
File XFCB fundons also require the calling Drogfam m initialize byte 12. Ihc Rename 
.. . 
File function requires the calling program to place the new filename and rype in bytes 
17 through 27. 


BDOS open or make function calls require the calling program to intialize bytes 0 


throueh 12 of the FCB before malane the call. Usuallv. byte I2 is set to zero. In 
.. ' 


addition, if the file is m be processed from the beginning using sequential rcad or 
wrrte functions, bytc 32, cr, must be zeroed. 


Ahcr an k<:R nr amvatcd by an open or makc opcrarwn, a propram doc. not have 


to modify the PCB to perform vquenrtal rcad or wrote opcrarlonc In tact. byrrr 0 
thmuph II of an anwatcd FCB should nut he mod~ficd. Howcvrr, random LO 
functions require that a program set bytes 33 through 35 to the requested random 
m r d number prior to making the fundion call. 


Ftlc dwcctory entrrcs ma~nra~ncd 
~n the dlrcnory area of each dtrk have rhc ,.me 


format 3s tCRr. excluding byrcr 32 through 35. cxccpr fur bye 0 w h ~ h 
ronralnr rhc 


file's user numhcr Burh rhc O ~ c n 
Fllc snd Make Fdc tunmom br~ne. thew cntrscq. 


excluding byte 0, rnto memory'in the FCB specified by the calling program. All read 
and write operations on a file must spwfy an FCB activated m this manner. 
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The BDOS updates the memory copy of the FCB during file processing to maintain - 


the NmCnt position within the filc. During file write operations, the BDOS updates 
the memory copy of the FCB to record the allocation of data to the file, and at the 
termination of file processing, the Close File function permanently records this infor- 
mat~on on disk. Note that data allocated to a file during file write operations is not - 


completely recorded m the directory untd the calling program issues a Close File call. 
Therefore, a program that creates or modlfics files must clow the filer at the end of 
any write processing. Otherwise, data might be lost. 
- 


The BDOS Search and Delete functions suppon multiple or ambiguous filc refer- 
ences. In general, a question mark in the filename, filetype, or extent field matches 
any value ~n the corresponding positions of directory FCBE during a directory search - 


operatton. The BDOS search functions also recognize a question mark m the drive 
code field, and if spec~fied, they return all directory entries on the disk regardless of 
user number, including empv entries. A directory FCB that begins with ESH is an - 
empty directory entry. 


2.3.4 
File Amibutes 
- 


The Lgh-order bits of the FCB filename, fl', ..., 18'. and filetype, tl',tZ',t3', fields 
arc called atu>bute bits. Attributes b~ts are 1 bit Boolean fields where 1 indicates on 
or true, and 0 indicates off or false. Amibute bits indicate two kinds of attributes - 
within the file system: file amibutes and interface amibutes. 


The file attribute bits, fl', ...,M' and tl',cZ',t3', can indicate that a file has a defined 


file attribute. These birr are recorded in a file's directory FCBs. Fclc attributes can be - 


set or reset only by the BDOS Set File Attributes function. men the BDOS Make 
File function creates a file, it initializes all file attributes to zero. A program can 
Interrogate file anrlbutes in an FCB activated by the BDOS Open File funmon, or in - 
dlrecfory PCBs rrnumed by the BDOS Search For Fim and Search For Nexr functions. 


Note the BDOS file system ignores file attribute bits when it attempts to locate a file - 
in the directory. 


The file system defines the file amibute bits, tl',t%t3', 
as follows: 
- 


tl': 
Read-Only amibute - The file system prevents write operations to a file with 
the read-only amibute set. 
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t2': System amibutc - This anribute, if set, identifies the file as a CP/M 3 system 
file. System files are not usually displayed by the CP/M 3 DIR command. In 
addition, user-zero system files can be accessed on a read-only basis from other 
user numbers. 


t3': 
Archive attribute - Thlr anribute is designed for user wdmn archivc programs. 
When an archive program mpies a file to backup storage, ~t sets the archive 
attr~bute of the copied files. The file system automatically resets the archive 
attribute of a directory FCB that has been !.sued a write mmmand. The archive 
program can test this attribute in each of the file's directory FCBs via the BDOS 
Search and Search Next functions. If 111 directory FCBs have the archive attn- 
burc set, a indicates that the file has not bccn modified since the previous 
archive. Note that the CP/M 3 PIP utility supports file archival. 


Attributes fl' through f4' are available for definition by the user. 


The hintface amibutes are indicated by biu fS' through is' and cannot be used as 
file attribum. Interface attributes f5' and f6' can request options for BDOS Make 
Fie, Clov File, D e l e File, and Set Fllc Atniburn haions. Table 2-3 d&s options 
indicated by the f5' and f6' interface attr~bute bin for these functions. 


Table 2-3. BDOS Interface Amibutea 


BDOS Rncnon 
/ 
Interfare Amibute Dcf;nttia 


116. Close File 
f5' = 1 : Partial Close 
I 


119. Delete File 
f5' = 1 : Dclcte file XFCBs 


f6' = 1 : Assign password m 


file 


130. Set File Attributes 
f6' = 1 : Set file byte count I 


Section 3 discusses each interface amibute in detail in the definitions of the above 
functions. Amibutes fS' and f6' are always reset when control is returned to the 
calling program. Interface attributes fl' and fa' arc reserved for internal use by the 
BDOS file system. 
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2.3.5 User Number Conventions 
- 


The CP/M 3 User facility div~des each drwe directory into sixteen loscally inde- 
pendent directories, designated as urer 0 through user IS. Physically, all uscr direc- 
tories share the directory area of a drive. In most other aspem, however, they are 
independent. For example, file with the same name can exist on different user num- - 


bcrs of the same drive with no conflict. However, a single file cannot reside under 
more than one urer number. 
- 


Only one user number is active for a program at one time, and the current uscr 


number applies to all drives on the system. Furthermore, the FCB format does not 
contain any field that can be used to override the current user numbcr. As a result, - 
all file and directory operations reference directories associated with the current user 
numbcr. However, it is possible for a program to access files on different user num- 
bers; this can be accompl!shed by sming the user number to the file's urer number 
with the BDOS Set User hlnction before making the desired BDOS function call for - 
the file. Note that this technique must be used carefully. An error occurs if a program 
attempts to read or write to a file under a user number different from the user 
number that was active when the file was opened. 
- 


When the CCP loads and executes a transient program, it ~nitializes the urer num- 
ber to the value displayed in the system prompt. If the system prompt does not 
display a user number, user rero a implied. A nansient program can change its user - 


number by making a BDOS Set User function call. Changing the user number ~n thls 
way does nor affect the CCP's user number displayed ~n the system prompt. When 
the transient program terminates, the CCP's user number is restored. However, an - 
option of the BDOS Program Chain command allows a program to pass IS 
current 
user number and default drive to the chained program. 


User 0 has special properties under CP/M 3. When the current user number is not - 


equal to zero, and 11 a requested file is not present under the Nrrent user number, 
the file system automatically attempts to open the file under user rero. If the file 
exists under user rero, and if it has the system attribute, t2', set, the file is opened - 


from user zero. Note, however, that files opened in this way annot be written to; 
they are available only for read access. This procedure allows utihtics that may 
indude overlays and any other commonly accessed files to be placed on user zero, - 
but also be available for access hmm other user numbers. As a result, mmmonly 
needed utilities need not be mplcd to all user numbers on a directory, and you can 
control which user zero files arc directly accessible from other user numbers. 
- 


- 
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2.3.6 
Directory Labels and XFCBs 


The BDOS file system includes two special types of FCBs: the XFCB and the 


Directory Label. Ihe XFCB is an extmdcd FCB that optionally can be assoc~ated 
- 
with a file m the dirmory. If present, it mntains the file's password. Note that 
password protected files and XFCBs are supported only m the banked vcnion of 
CP/M 3. T h e format of the XFCB follows. 


Figure 2-1. XFCB Format 


DR 


s1,s2,rc - 
- 
password - 
reserved - 


- 
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FILE 


drive code (0 - 16) 
filename field 
filetype field 
password mode 
ba 7 - Read mode 
bit 6 - Write mode 
bit 5 - Delete mode 
" - btt references are right to Icft, 
relative to 0 


reserved for system use 
8-byre password field (encrypted) 
8-byte reserved area 


TYPE PM Sl 
PASSWORD 
S2 
RESERVED 
RC 
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An XFCB can be created only on a drive that has a directory labd, and only if the 
directory lahi has activated password protection. For drives in this state, an XFCB 
can be created for a file in two wavs: bv the BDOS Make function or by the BDOS 
Write File XFCB function. The BDOS ~ a k c 
function creates an XFCB if the calling 


program requests that a password be assigned to the created file. The BDOS Write 
File XFCB function can be used to assign a password to an existing file. Note that in 
the directory, an XFCB is identified by a drive byte value, byte 0 in the FCB, equal 
to 16 + N, where N equals the user number. 


For its drive, the directory label specifies 11 file password support is to be activated, 
and d date and time stamping for filer is to be performed. The hnnat of the Dlrec- 
tory Label fallows. 


Rgum 2-2. Dirmory Labd Format 


DR 


dr 
- 
drive mde (0 - 16) 
name 
- 
Directory Label name 


type 
Directory Label type 
dl 
- 
Directory Label data byte 
bit 7 - require passwords for password 


protected files 
bit 6 - perform access time stamping 
bit 5 -perform update time stamping 
ba 4 - vcrform create time stamvlne. 


00 
0 1 . . 
09 
1 2 1 3 1 4 1 5 
16 . . . 
2 4 . 28 


NAME 


. - 


bit 0 - Directory Label exists 
" - bit references are right to Icft, 


relative to 0 


sl,s2,rc 
- 
d a 


password - 
(I-byte password field (encrypted) 


tsl 
- 
4-bpc creation time stamp fidd 


ts2 
- 
4-byte update tlme stamp field 
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- 
Only one Directory Label can exist in a drive's directory. The Directory Label name 
2nd type fields are not used to search for a Directory Label; they can be used m 
identify a disk. A Directory Label can be created, or in fields can be updated by 
- 
BDOS funalon 100, Set Dtrcctory Labcl. This function can also assign a Directory 
Label a 
The Directory Labcl 
if assigned, cannot be d r a m - 


vented, whereas file password protection is an option controlled by the Directory 
Label. Thus, access to the Directory Labd password provider a !4nd of supcr-user 
- 
StaNs on that drive. 


The nonbankcd vcrrmn of CPLl 3 doer not ~uppon file parrwordr However, II 


docs pmvlde pvrword pmvmon of hmnory lahelr Ihc CPM 1 RSX, DIRU)I..KSX, 
- 
which ~m~lemcnrr 
BDOS Funcnon 100 ~n the nonbanked vcrrlon of CP M 3. pro 


"ides thii support. 
- 
The BDOS file system has no function to read the Dimtory Label FCB directly. 
However, the Directory Labcl data byte can be read d i d y with the BDOS Funcuon 
101, Rtmm Directory Labd. In addition, the BDOS Search functions, with a ? in the 
- 
FCB drive byte, can be used to find the Directory Label on the default drive. In the 
directory, the Directory Labcl is identified by a drive byte value, byte 0 in the FCB, 
equal to 32,20H. 
- 
2.3.7 File Paaswords 


Only the banked version of CP/M 3 supports file passwords. In the nonbanked 
- 
version, all BDOS functions with password related options operate the same way the 
banked version does when passwords are not enabled. 


Files can be assigned passwords in nuo ways: by the Make Filc function or by the 
- 
Write File XFCB funct~on. A file's password can also be changed by the Write File 
XFCB fundon ~f the original password is supplied. 
- 
Password protection is provided in one of t h m modes. Table 2-4 shows the differ- 


mce in access level allowed to BDOS functions when the password is not supplied. 
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Table 24. Password Pmtsction Moda 


1. Read 
The file cannot be read. 


12. Write 
The file can be read, but not modified. I 


13. Delete 
The file can be modified, but not 
I 


deleted. 


If a file is password protected in Read mode, the password must be supplied to open 
the file. A file protected in Write mode cannot be written to without the password. 
A file protected in Delete mode allows read and wrxte access, but the user must 
soccifv the assw word to delete the file. rename the file. or to modifv the file's attri- 
. , . 
butes. Thus. oassword orotcdon in mode 1 imoller mode 2 and 3 orotcmon. and 
. 


mode 2 protecuon ~mpltes mode 3 proternon All three modes requtre the user to 
spmfy the password m delete the fil+ rename the file, or m m d f y the file's ambuts. 


If the correct password is supplied, or if password pmtcdon is disabled by the 


Dlrectory Label, then access to the BDOS functions IS the same as for a file that is 
wt password protected. In additlo", the Search For First and Search For Next func- 
tions are not affected by file passwords. 


Table 2-5 lisn the BDOS hnctions that test for password 


Table 2-5. BDOS F 
d 
s 
That Test For Password 


Open File 
Delete File 
Rename Filc 
Set File attribute^ 
Truncate Filc 
Set Directory Label 
Write File XFCB 
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File passwords are eight bytes in length. They are maintained in the XFCB Direc- 
tory Label in encrypted form. To make a BDOS function call for a file that requires 
a password, a program must place the password in the first eight bytes of the current 
DMA, or specify it with the BDOS hmction, Set Default Password, prior to maktng 
the function call. 
Note: the BDOS keeps an assigned default password value until it is replaced with a 
new assigned value. 


2.3.8 File Date and Time Stunpr 


The CP/M 3 File System uses a spcclal type of directory enuy called an SFCB to 
record datc and time stamps for files. When a directory has been initialized for dare 
and time stamping, SFCBr reside in every fourth position of the directory. Each SFCB 
maintains the date and time stamps fur the previous three directory entries as shown 
~n Figure 2-3. 


Figure 2-3. Directory R-rd 
with SFCB 


21 


- 
This figure shows a directory mcord that contains an SFCB. Directory mmrds consist 
of four directory entnes, each 32 bytes long. SFCBs always occupy the last position 
of a directory record. 
- 


The SFCB directory item contains five fields. The first field is one byte long and 
contains the value 21H. This value ldentlfies the SFCB in the directory. The next 
- 
three fields, the SFCB subfields, contain the datc and time stamps for their corre- 
sponding FCB entries in the directory record. These fields are 10 bytes long. The last 
byte of the SFCB is reserved for system use. The format of the SFCB subfields is 
- 
shown in Table 2-6. 
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FCB 1 


FCB 2 


FCB 3 


STAMPS FOR 
FCB l 


STAMPS FOR 
FCB 2 
STAMPS FOR 
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Table 2-6. SFCB Subfields Format 
- 


SFCB Subfield Contents 


Update Date and Tlme Stamp field 
Password mode field 
9 
: 
Reserved 


An SFCB subfield contains valid information only ~f its corresponding FCB in the 
directory record is an extent zero FCB. This FCB 1s a file's fint directory entry. For - 
password protected files, the SFCB subfield also contains the password mode of the 
file. This field is zero for files that are not password ~rotected. The BDOS Search and 
Search Next functions can be used to accers SFCBs directly. In addition, BDOS - 
Function 102 can return the file date and time sramps and password mode for a 
specified file. Refer to Section 3, function 102, for a desuiptlon of the format of a 
date and time stamp field. 
- 


CP/M 3 supports three types of file stamping: mate, acmr, and update. Create 


stamps record when the file was created, access stamps record whcn the file was last 
opened, and update stamps record the last time the file was modified. Create and - 
accers stamps share the same field. As a result, file access stamps overwrite any create 
stamps. 
- 


The CP/M 3 utility, INITDIR, initializes a directory for date and time stamping by 
placing SFCBs in cvcry fourth directory entry. Date and time stamping s not sup- 
ported on disks that have not been initialized in this manner. For initialized disks the 
disks' Directory Label determines the type of date and time stampmg supported for - 


files on the drive. If a disk does not have a Directory Label, or if it is Read-Only, or 
if the dist's Dirmory Label docs nor specify date and time stampmg, then dare and 
time stamping for files IS not performed. Note that the Directory Label is also time - 
stamped, but thew stamps are nor made in an SFCB. Time stamp fields in the last 
eight bytes of the Directory Label record whcn it was created and last updated. 
Access stamping for D~rectory Labels e not supported. 
- 
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- 
The BDOS file system uses the CP/M 3 system date and time when it recotds a 
date and time stamp. This value rr maintained in a field in the System Control Block 
(SCB). On CPiM 3 systems that support a hardware clock, the BlOS module directly 
- 


updam the SCB system date and time field. Otherwise, date and t~me stamps record 
the last initialized value for the system date and tlmc. The CPiM 3 DATE utility can 
be used to sct the system date and time. 
- 
2.3.9 
Record Blochg and DcbIocLing 


Under CPiM 3, the logical record size for disk VO is 128 bytes. This is the basic 


unlr of data transfer bcrwccn thc upcrarmp system and translent programs Howrvcr, 
- 
on dl,k. the rccord snc IS nor rertr~cvd to 128 hytcr Thcrc records, callcd phyr~cal 
records, can range from 128 bvrcs to 4K bytes ~n s ~ z c Record hlaxklng and deblock- 
mg is rcqu~rcd on systems that support drives with physical record siics larger than 
128 bytes. 


The process of building up physical records from 128 byte logical records is called 


m o r d blockmg. This process is required in write operations. W e reverse process of 
breaking up physical records into their component 128 byte logcal records is called 
w r d deblockmg. This process is required in read operations. Under CPiM 3, rccord 
blocking and deblocking 8s normally performed by the BDOS. 


Record deblocking implies a read-ahead operation. For example, if a transient 
program makes a BDOS function call to read a logical record that resides at the 
beginning of a phyrlcal record, the entire physical record is read into an internal 
buffer. Subsequent BDOS read calls for the remaining logical records access the 
buffer instead of the disk. Conversely, record blocktng results in the postponement 
of physical wrrte operations but only for data write operations. For example, if a 
transient program makes a BDOS write call, the logcal record 1s placed I" a buffer 
equal m s l u to the physical record size. The write operation on the physical record 
buffer is postponed until the buffer is needed m another UO operation. Note that 
under CPiM 3, directory write operations are never postponed. 


Postponing physical record write operations has implications for some applications 
programs. For those programs that tnvolve file updatmg, it is often critical to guar- 
antee that the state of the file on disk ~arallels the state of the file in memorv after 
, 
~ 


the update operation. This is only an issue on sysfems where physical wnre opcra- 
tions are postponed because of record blocking and deblocking. If the system should 
crash while a physical buffer is pending, data would be lost. To prevent this loss of 
data, the BDOS Flush Buffcrs function, fundon 48, can be called to force the write 
of any pending physical bufhrs. 
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Note: 
the CCP automatically discards all pending physical data bufferr when it 
receives control following a system warm start. However, the BDOS filc system 
automatically makes a Flush Buffen call in the Close File function. Thus, it is suffi- 
cient to close a file to ensure that all pending physical buffers for that file are written 
to the disk. 


2.3.10 
Multi-Smor UO 


CP/M 3 can read or writc multiple 128-byte records in a s~ngle BDOS function 
call. This process, called multi-sector UO, s useful pr~marily in sequentla1 read and 
writc operations, particularly on drives with physical record sizes larger than 128 
bytes. In a multi-sector UO operation, the BDOS filc system bypasses, when possible, 
all intermediate record buffering. Data is transferred directly between the TPA and 
the drive. In addition, the BDOS informs the BIOS when it s reading or writing 
multiple physical records m sequence on a drive. The BIOS can use this information 
to further optimlzc the U0 operation resulting in even bmer performance. Thus, the 
primary objective of multi-sector UO is to improve sequential UO performance. The 
actual Improvement obtained, however, depends on the hardware environment of the 
host system, and the ~mplementation of the BIOS. 


The number of records that can be supported wlth multi-sector UO ranges from 1 
to 128. Thts value can be set by BDOS function 44, Set multi-sector Count. The 
multl-sector count is set to one when a transient program begins cxmtion. However, 
the CPiM 3 LOADER module executes with the multi-sector Count set to 128 unless 
the available TPA space is less than 16K. In addition, the CPiM 3 PIP utility also 
sets the multi-sector count to 128 when sufficient buffer space e available. Note that 
the greatest potential performance increases are obtained when the multt-sector count 
is set to 128. Of course, this requires a 16K buffer. 


The multi-sector count determines the number of operations to be performed by 
the following BDOS functions: 
I 
Sequential Read and Write functions 
. 
Random Read and Write functions including Write Random with Zcro Fill 


If the multi-sector count is N, calling one of the above functions is equivalent to - 


making N function calls. If a multi-sector UO operation is interrupted wtth an error 
such as rcadine unWritten data. the file system r a m s in register H the number of 
128-byte records sumssfully processed. 
- 
- 
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2.3.11 Disk Rast and Rsmovablc Media 


The BDOS functions, Disk Reset (function 13) and Reset Drive (hmction 37) allow 
a program to control whcn a dla's directory is to be minfitialired for file operations. 
- 
This process of inrtiahr~ng a disk's directory is called logging-in the dnve. When 
CP/M 3 is mld stamd, all drives are in the reset state. Subsequently, as drives are 
referenced, they are automatically logged-m by the file system. Once logged-in, a 
drive remains in the logged-in state until it a reset by BDOS function 13 or 37. 
- 
Following the m e t operation, the drive is again automatically logged-in by the file 
systcm whcn it is n u t used. Note that BDOS functions 13 and 37 havc sim~lar effens 
except that function 13 1s directed to all drives on the system. Any combination of 
- 
drives can be reset with Function 37. 


Logging-in a drwe mnsists of several steps. The most imponant step is the mitiah- 
- 
ration of the drive's allocation vector. The allocation vector records the allocation 
and deallocation of data blocks to files, as files are created, extended, deleted, and 
truncated. Another function performed during drive log-in is the ilurialiratian of the 
directory check-sum vector. The file system uses the check-sum vector to detect media 
- 
changes on a drive. Note that permanent drives, which arc drives that do not support 
media changes, might not havc check-sum vectors. If directory hashing has been 
specified for the drive, a BlOS and GENCPM option, the file system creates a hash 
- 
table for the directory during log-in. 


The primary use of the drive reset functions is to prepare for a media change on a 
drive. Subsequently, when the drive is accessed by a BDOS function call, the drive is 
- 
automatically logged-in. Resetting a drive has rwo important side effects. Fint of all, 
any pending bloclungldeblodt~ng buffers on the reset drwe are discarded. Secondly, 
any data blocks that have been allocated to files that have not been closed are lost. 
- 
An application program should close files, panlcularly files that have been wrincn to, 
prror to resetting a drive. 


- 
Although CP/M 3 automatically relogs in removable media when media changes 
are detected, the applicanon program should still cxpllcitly reset a drive before 
prompting the user to change disks. 


- 
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2.3.12 File Byte Counts 


Although the logical record size of CP/M 3 is m m a e d m 128 bym, CP/M 3 does 


provide a mechanism to smm and retrieve a byte count for a file. This facility can 
identify the last byte of the last record of a file. The BDOS Compute Fllc Size 
function returns the random record number, plus 1, of the laat record of a file. 


The BDOS Set File Amibutes function can set a file's byte count. Conversely, the 
Open function can m u m a file's byte count to the cr field of the FCB. The BDOS 
Search and Scarch N u t functions also return a file's byte count. These functions 
return the byte count in the 5 1 field of the FCB returned m the cu-t 
DMA buffer 


(see BDOS Functions Returned 17 and 26). 


Note that the file system does not access or update the byte count value in file read 
or write operations. However, the BDOS Make File funmon does set the byte count 
of a file to zero when it creates r file in the directory. 


2.3.13 BDOS h 
r 
Hmdling 


The BDOS file system responds to error situations in one of three ways: 


Method 1. 
It returns to the calling program with murn codes in register 
A, H, and L identifying the error. 


Method 2. 
It displays an error message on the console, and branches to 
the BlOS warm stan entry point, thereby terminating execu- 
tion of the calling program. 


Method 3. 
It displays an error message on the console, and returns to 
the calling program as in method 1. 


The file system handles the majority of errors it detect. by method 1. Two examples 
of this kind of error are the file not found error for the onen function and the madine 
unwtinen data error for a read function. More serious errors. such as dirk VO errors. 
arc usually handled by mehod 2. Enors m thlr cangoty, called physld and emended 
errors, can also be reported by methods 1 and 3 under program control. 
- 
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The BDOS Error Mode, which can uist in three states, determines how the file 
system handles physical and extended erron. In the default smte, the BDOS displays 
the error message, and terminates the calling program, method 2. In murn error 
mode, the BDOS returns control to the calling program with the error identified in 
registers A, H, and L, method 1. In return and display mode, the BDOS returns 
contml to the calling program with the error identified m rewsccr~ A, H, and I., 
and 
also displays the error message at the consolc, mcthod 3. While both mum modes 
protect a program from termination because of a physcal or extended crror, the 
return and display mode also allows the calling program to take advantage of the 
budt-in error reporting of the BDOS file system. Physical and extended erron arc 
displayed on the console in the following format: 


CP/M Error on d: error message 
BDOS function = nn Filc = filenamc.typ 


where d identifies the drive selected when the crror condition is dmcted; error mcs- 
sage identifies the error; nn is the BDOS fundon number, and filcname.typ identifies 
the file specified by the BDOS function. If the BDOS function did not involve an 
FCB, the file information is omitted. Note that the second line of the above error 
message is displayed only in the banked version of CP/M 3 if expanded error message 
reporting rs requested in GENCPM. It is not displayed in the nonbankcd version of 
CP/M 3. 


The BDOS physical errors are identified by the following crror mssagcs: 


D~sk U0 
Invalid Drive 
Read-only Filc 
I 
Read-only Disk 


The Disk VO error rnults from an error condition returned to the BDOS from the 
BIOS module. The file system makn BIOS read and write calls to execute file-related 
BDOS calls. If the BIOS read or write routine detcm an error, it returns an error 
code to the BDOS msulung in this error. 


The Invalid Drive ermr also resuln from an error condition returned to the BDOS 
from the BIOS module. The BDOS makes a BIOS Select Disk call prior to accessing 
a drive to perform a requested BDOS function. If the BlOS does not support the 
selected disk, the BDOS returns an error code resulting in this error message. 
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The Read-only File error is returned when a program attempts to write m a file 
that a marked with the Read-only attribute. It is also returned to a program that 
attempts to write to a system filc opened under user zero from a nonzero user 
number. In additlo", this e m r is reNrned when a program attempts to write to a 
file password protected m Write mode if the program does not supply the correct 
password. 


The Read-Only Disk error is returned w h a a program writes to a disk that is in 


read-only status. A drive can be placed in read-only status explicitly w~th the BDOS 
Writc Protea Disk function. 


The BDOS extended errors are identified by the fallowing error messages: 


1 Password Error 
1 File Exists 
I 
? m Filename 


The File Password error is returned w h a the file password is not supplied, or 
when it is incorrect. Wis error is reported only by the banked version of CP/M 3. 


The File Exists error is returned by the BDOS Make Filc and Rename Filc func- 
tions when the BDOS detects a conflia such as a duplicate filename and w e . 


The ? in Filename ermr IS murned when the BDOS dctna a ? in the filename or 


type field of the passed FCB for the BDOS Rename Filc, Set File Aunbutea, Open 
File, Make File, and Truncate File functions. 


The following paragraphs describe the error m u m code conventions of the BDOS 


filc system functions. Mast BDOS file system functions fall inm three categories in 
regard to return codes: they return an Error Code, a Directory Code, or an Error 
Flag. The error conventions of CP/M 3 are designed to allow programs wrimn for 
earlier versions of CP/M to run without mod~fication. 


The following BDOS functions rrmm an Error Code m register A. 


20. Read Sequential 
21. Write Sequential 
33. Read Random 
34. Wrm Random 
40. Write Random w/Zcro Fill 
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We Error Code definitions for register A are shown in Table 2-7. 


Table 2-7. Repistcr A BDOS Error Codes 


Code - 
00 : 
255 : 


I 
Messing 


Function successful 
Physical error : refer to register H 
Reading unwritten data or no available directory space (Write 
Sequential) 
No available data block 
Cannot close current enent 
Seek to unwritten extent 
No available dlrectory space 
Random record number out of range 
Invalid FCB (prev~our BDOS dose call returned an error code 
and invalidated the FCB) 
Medm Changed (A media change war detected on the FCB'r 
drive after the FCB war opened) 


- 


For BDOS read or write functions, the file system also sets register H when the 
returned Ermr Code is a value other than zero or 255. In thlr case, register H 
- contams the number of 128-byte wards successfully read or wrinm before the crmr 


war encountered. Note that register H can contdln only a nonzem value if the calling 
program has set the BDOS Multi-Sector Count to a value other than one; otherwise 
register H is set to zero. On successful funaions, Error Code = 0, register H is also 
- set to zero. If the Error Code equals 255, register H contains a physical error code 


(see Table 2-11). 
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The following BDOS functions mum a Directory Code in register A: 
- 


15. Open Filc 
16. Close Fllc 
17. Search For First 
18. Search For Next 
19. Delete File 
22. Make File 
23. Rename File 
30. S n File Attributes 
35. Compute Filc Size 
99. Truncate File 
100. Set Directory Label 
102. Read File Date Stamps 
" 103. Write Flle XFCB 
and Password Mode 


-Th!s function ir supported in the DIRLBLXSX in the nonbanked version of 


CP/M 3. 
" -This function is supported only in the banked version of CP/M 3. 
- 


The Dirmory Code definluons for reester A are shown in Table 2-8. 
- 


Table 2-8. BDOS Direcmry Coda 


I Code 
/ 
Meonin. 
I 


With the exception of the BDOS search functions, all functions in this category - 
m r n with the directory code set to zero on successful returns. However, for the 
search functions, a succasful Directory Code also ldcntifies the relative starting poa- 
tlon of the dlrcctoty entry ~n the calltng program's current DMA buffer. 
- 
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If the Set BDOS Error Mode function is used to place the BDOS in return error 


mode, the following functions r a m an Error Flag on physical errors: 


14. Select Disk 
46. Get Disk Free Space 
48. nuah Bufbn 
98. Free Block 


101. Return Directory Label Data 


The Error Flag definition for register A is shown in Table 2-9. 


Tablc 2-9. BDOS k 
r 
Flags 


Meaning 


255 : 
physical error : refer to register H 


The BDOS returns nonzero values in register H to identify a physical or extended 


error if the BDOS Error Mode is in one of the return modes. Except for functions 
that return a Directory Code, register A equal to 255 indicates that register H !den- 
tlfies the physical or atended error. For functlonr that return a Directory Code, if 
register A equals 255, and rcgstcr H a not equal to zero, register H ldcnrifics the 
physical or extended error. Table 2-10 shows the physical and extended error codes 
returned in register H. 
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Table 2-10. BDOS Physical and Extended Errom 


Meaning 


no crmr, or not a register H error 
Disk VO error 
Read-Only Disk 
Read-Only File or File Opened 
under user zero from another user 
number or file password protected 
in wr~tc mode and correct pass- 
word not specified. 
Invalid Drive : drive select error 
Password Error 
Frlc Exrsts 
? in Rlename 


The following rwo hmons represent a special case because they retum an addms 


in registers H and L. 


27. Get Addr(Allrx) 
31. G n Addr(Disk Parms) 


When the BDOS is in mum error mode, and it detects a physical error for these 
functions, it returns m the calling program with registers A, H, and L all set to 255. 
Othenulse, they m u m no error code. 


2.4 Page Zero Initialization 


Page Zero is the region of memory located from OOOOH to OOFFH. This region 
contains several segments of code and data that are used by transient programs while 
mning under CP/M 3. 'The mde and data arras arc shown in Table 2-11 for reference. 
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Table 2-11, Page Zero Areas 


OOOOH - 0002H Contains a jump instruction to the BlOS warm start entry 


pomr at BIOS-base + 3. The address at location OOOlH can 
also be used m make direct BlOS calls to the BlOS console 
status, console input, console output, and list output primitive 
functions. 


L o u t i a 


I 0003H - 0004H (Reserved) 
I 


Contents 


000SH - 0007H Contains a jump instruction to the BDOS, the LOADER, or 
to the most recently added RSX, and serves two purposes: 
JMP OOOSH provides the primary entry polnr to the BDOS, 
and LHLD 0006H places the address field of the jump 
instruction in the HL register pair. This value, minus one, is 
the highest address of memory available to the translent 


I 


program. 


From 
TO 


I 0008H - 003AH Reserved interrupt locations for Restarts 1 - 7 
I 
I 003BH - 004FH (Not currently used - m r v e d ) 
I 


OOSOH 
Identifies the drive from which the transient program was load- 
ed. A value of one to sixteen identifies drives A through P. 


OOSlH - OOS2H Containsthe address of the ~a~swordfield 
of the fint command- 


tall operand ~n the d c f a u l r ' ~ ~ ~ 
buffer bcenn~ng at OOSOH 


Thc < CP rcts thlr field to zero 11 no password for the fist 
command-tad operand is specified. 


0053H 
Contains the length of the password field for the first command- 
tail operand. The CCP also sm this field to zero if no password 
for the fint mmmand tail is specified. 


0054H - OOSSH Contams the address of the password field of the second mm- 


mand-tail operand in the default DMA buffer beenning at 
0080H. The CCP sets thss field to zero if no password for the 
second mmmmd-rail operand is swcified. 
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From 
To 


0056H 
Contains the length of the password field for the second com- 
mand-tail operand. Thc CCP also sea this field to zero if no 
paasword for the second command tall is specified. 


Table 2-11. 
(continued) 


0057H - OOSBH (Not currently used - reserved) 
I 


Location 


OOSCH - 007BH Default File Control Block, FCB, arca 1 initialized by the CCP 
from the first command-tail operand of the command lme, if 
~t exists. 


Contents 


006CH - 007BH Default File Control Block, FCB, arca 2 initialized by the CCP 
from the second command-tail operand of the command line, 
if a exists. 


Note: 
this area overlays the last 16 bytes of dcfault FCB 
area 1. To use the information in thla area, a transient program 
must copy it to another location before using FCB arca 1. 


007CH 
Current record position of default FCB area 1. This field is used 
with default FCB arca 1 in sequential record processing. 


007DH - 007FH Opr~onal dcfault random rrmrd porluon Thtr field 8s an rxten- 


won of default FCR area 1 uxd ~n random rccord procrrrlng I - 
I 0080H - OOFFH Default 128-byte disk buffer. This buffer is also filled with the 
command tail when the CCP loads a transient program. 
I - 


- 
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- 
The CCP lnloaltur Page Zem pnor m InlruMg a vansrrnt pmgnm. The fields at 


OOSOH and above are ~nmnl~zcd 
fmm the mmmand line tnvoknng the translent pro- 
gram. The command l~nc format was desmbed m dnarl m Section 1 6 2. To sum- 
marize, a command line usually take. the form: 


- 
where 


<mmmand tail> 
=> (no mmmmd tail) 
=> <file spec> 
- 
= > <file spec><delimiter><file SF> 


- 
The CCP inidalirea the mmmnd drive field at OOSOH m the drive index, A = 1, ..., 
P = 16, of the drive fmm which the transient pmgram was loaded. 
- 
The default FCB at OOSCH is defined if a mmmand tail is entered. Othenvise, the 
fields at OOSCH, 0068H m 006BH are sa to binary zeros, the fields from OOSDH to 
0067H are set to blanks. The fields at OOSlH thmugh 0053H are set ~f a password 
- 
is spcufied for the first <file spec> of the command tail. If not, these fields are set to 
zero. 


- 
The default FCB at 006CH is defined zf a semnd <file spec> exists in the mm- 


mand tail. Othenvise the fields at 006CH 0078H m 007BH arc set m binary zeros 
the fields from 0 0 5 6 ~ 
m 0067H arc M) to b l a h . The fields at 00S4H thou& 


0056H are sa if a password is specified for the semnd <file spec> of the command 
- 
tail. If not, thcac fields are set to zero. 


Transimt programs often use the default FCB at OOSCH for file owations. This 
- 
FCB may even he used for random file access baause the three by& 
smrnng at 


007DH are avrdablc for thlr purpose. However, a translent program must copy the 
contents of !he default FCB a1 006CH to another area bcfore uslne the dcfault FCB 
at OOSCH, bccausc an open operatlo" for the dcfault FCB at O O S ~ H 
ovcrwritcs the 
- 
PCB data at 006CH. 
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The default DMA address for transient programs is 0080H. The CCP also initial- 
izes this area to contain the command tail of the command line. The first por~tion - 


contains the number of characters in the command h e , followed by the command 
line characters. The charaaer following the last command tail character is set m 
b~nary zero. The command l l n ~ characters are preceded by a leading blank and are - 
translated to ASCII upper-case. Because the 128-byte revon beginning at 0080H is 
the default DMA, the BDOS file system moves 128-byte records to this area with 
read operations and accesses 128-byte records from thls area with write operations. - 
The transient program must extram the command tall information from this buffer 
before performrng file operations unless it explicitly changes the DMA address with 
the BDOS Set DMA Address function. 
- 


The Page Zero fields of OOSlH through 0056H locate the password fields of the 
first nuo file specifications in the command tail if they exist. These fields are provided 
so that transient programs are not required m parse the command tail for password - 
fields. However, the transient program must save the password, or change the DMA 
address before performing file operations. 


The following example illustrates the initialization of the command line fields of - 


Page Zero. Assuming the following command line is typed at the console: 


A hexadecimal dump of 0050H m 00A5H would show the Page Zero initialization 
performed by the CCP. 


End of Section 2 


O DIGITAL RESEARCHI* 


2-38 


- 
Section 3 
BDOS Function Calls 


This section descrlbcs each CP/M 3 system function, including the parameters a 
- program must pass when calling the function, and the valuer the function returns to 
the program. The functions are arranged numerically for easy reference. You should 
be familiar with the BDOS calhngconventions and othcrmncepn presented in Sectlon2 
- 
before ref~lencing this section. 


The System Reset function terminates Q calling pmgrzm and returns control to 
the CCP via a warm stan sequence (see Section 1.3.2). Calhng this function has the 
- 
same effect as a jump to location OOOOH of Page Zero. 


Note that the disk subsystem is not reset by System Reset under CP/M 3. The 
- calling program can pass a return code to the CCP by calling Function 108, GttlSrt 


Program Return Code, prior to making a System Reset call or jumping to location 
0000H. 


3 BDOS Calls: 
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Regstcr C: 01H 


Returned Value: 


Ihe Console Input function reads the ncn character from the logical console, 


CONIN:, to register A. Graphic chaacters, along with carriage return, line-feed, and 
backpace, GIRL-H, are echoed m the mnsolc. Tab characters, GIRL-I, are expanded 
m columns of 8 characters. CTRL-S, CTRL-Q, and CTRL-P are normally intercepted 
as described below. All other non-graphxc characters are returned in register A but 
arc not echoed to the console. 


When the Console Modc is in the default state (see Section Z.Z.l), Function 1 
intercepts the stop srroll, ClXL-S, start scroll, CTRL-Q, and stadstop printer echo, 
CIRL-P, characters. Any characters that are typed following a CTRL-S and preced- 
ing a CIRL-Q arc also intercepted. However, if startlrtop scroll has been disabled 
by the Console Modc, the CTRL-S, CIRL-Q, and CTRL-P characters are nor mter- 
ceptcd. Instead, they are returned in regirter A, but are not echoed to the console. 


If prlnter echo has been invoked, all characters that are Khoed to the console are 


also sent to the list dcvlu, LST:. 


Function 1 does not mum control to the calling program untd a non-intercepted 


character is typed, thus suspend~ng execution if a character a not ready. 


- 
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Registers C: OZH 
E: ASCII Character 


- 
The Console Output function sends the ASCII character from register E to the 
logical console device, CONOUT:. Whur the Console Mode is in the default state 
(see Section 2.2.11, Function 2 expands tab charuara, CTRL-I, in columns of 8 
- 
characters, checks for stop scroll, CTRL-S, sran saoll, CTRL-Q, and echoes charac- 
ters to the logical 1st device, LST:, if pnntcr echo, CTRL-P, has been invoked. 


- 


3 
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BDOS FUNCTION 3: AUXILIARY INPUT 


Entry Parameters: 
Register C: 03H 


Returned Value: 
Register A: ASCII Character 


We Auxiliary Input function reads the next character from the logical auxiliary 
input device, AUXIN:, into register A. Connol does not return to the calling program 
until the character is mad. 


- 
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- 


Registers C: 04H 
E: ASCII Character 


- 
The Auxiliary Ourput function sends the ASCII character from register E to the 


logical auxiliary output device, A n o n . 
- 


- 
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- 


Rcgistcrs C: OSH 


E: ASCII Character 


The List Output function smda the ASCII character in register E to the logical list - 


doicc, LST:. 
- 


BDOS FUNCTION 6: DIRECI CONSOLE VO 


Entry Parameten: 


Registers C: 06H 
E: OFFH (inpudstrrus) or 
OFEH (status) or 
OFDH (input) or 
char (output) 


Returned Value: 


Register A: char or rtams (no value) 


- 
CP/M 3 Prognmmcr's Guidc 
3 BDOS Calls: Function 6 


CP/M 3 supports direct VO m the logical mnsole, CONIN:, for those specialized 


applications where unadorned console cnput and output is required. U s Direct Con- 
sole VO carefully because it bypasses all the normal control character functions. 
Programs that perform d i m UO through the BlOS under previous releases of CP/M 
should be changed to use dirm UO so that they can be fully supported under futuce 
releases of MPlM and CP/M. 


- 


A program calls Function 6 by passing one of four different values in register E. 


The values and their meaning arc summarized in Table 3-1. 


- 
- 
- 
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I OFFH 


Console input!stams command r a m s an input character; if no 
character is ready, a value of zero is renuned. 


Table 3-1. Function 6 Entry P-ctcn 
- 


OFEH 
Console status command (On mum, register A contains 00 if no 
character is ready; otherwise it contains FFH.) 


Register 
E vclluc 


OFDH 
Console input command, returns an input character; this h c - 
tion will suspend the calling process until a character is ready. 


Mcaninr 


ASCII 
Function 6 assumes that register E mntalns a valid ASCII char- 


character 
acter and sends lt to the console. 


- 
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- 


Entry Parameters: 


Register C: 07H 


Rcturned Value: 
Register A: Auxiliary Input Status 


The Auxiliary Input Status function returns the value OFFH m register A if a 
- 
character is ready for input from the logical auxiliary input device, AUXIN:. If no 
character is ready for input, the value OOH is returned. 


3 BDOS Csllr: 
Function 8 
CP/M 3 Programmer's Guide - 


- 


Register C: OSH 


Returned Value: 


nlhc Aurlllary Output Srarur hrncnon rcturnr the value OFFH m rrgster A lf the 


loplcal auxrl~ary output dcvrcr, AUXOUl., a ready to accept a character for output. - 
If the device a not ready for output, the value OOH is returned. 
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Reesters 
C: 09H 
DE: String Addms 


The Print String function sends the character strlng addressed by register pair DE 


m the logical console, CONOUT:, until rt encountem a delimiter ~n the string. UEU- 
ally the delimiter is a dollar sign, $, but a can be changed to any other value by 
Function 110, W S e t Output Delimiter. If the Console Mode is m the default state 
(see Section 2.2.1). Function 9 expands tab characters, CTRL-I, in mlumns of 8 
characters. It also checks for stop scroll, CTRL-S, stan scroll, CTRL-Q and echoes 
to the logcal list device, LST:, if pnnrer echo, CTRL-P, has been invoke;. 


!l 
DIGITAL RUFAICH' 


3-11 


3 BDOS Calls: Function 10 
CP/M 3 Programmer's Guide - 


Registers C: OAH 


DE: Buffer Address 


Returned Value: 
Console Characters in Buffer 


where nu is the maximum number of characters which the buffer holds, and nc is 
the number of characters placed m the buffer. The characters entered by the operator - 


follow the nc value. The value mx must be set prior to making a Function 10 call 
and may mnge in value from 1 to 255. Sming mx to zero IS equivalent to setting mx 
to one. The value nc Ir murned to the calling program and may range from zero to - 
mx. If nc c nu, thm uninatalized positions follow the last character, denoted by ?? 
in the figure. Note that a terminating rrmm or hne feed character is not placed in 
the buffer and not indudcd ~n the count nc. 
- 


The Read Console Buffer funaion reads a ltne of edited console mput kom the - 


logical console, CONM:, to a buffer that register pair DE addresses. It terminates 
input and returns to the calling program whcn it encounters a return, CTRL-M, or a 
line fad, m-J, 
character. Function 10 also discards all input charactem after the - 
input buffer is filled. In addaion, it outputs a bell character, CTRL-G, to the console 
whcn it discards a character to signal the user that the buffer is full. The input buffer 
addressed by DE has the following format: 
- 


DE: +O + 1 + 2 + 3 +4 + 5 +6 +7 + 8 . .. +n 


If tegister pair DE is set to zero, Function 10 assumes that an initialized anput 


buffer is located at the cu-t 
DMA address (see Functlon 26, Set DMA Address). 


This allows a program to put a strmg on the screen for the user to cds. To rnitialize - 


the input buffer, sct characters cl through cn to the initial value followed by a binary 
zero termmator. 
- 
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- 
?? 
mx nc cl 
. . . 
C? 
c3 ~4 6 c6 ~7 


- 
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Whm a program calls Function 10 with an initialized buffer, Function 10 operates 
- 
as d the user had m c d in the mine When Function 10 encounters the binary zero 
termmator, a accepts mpur from rhc console At rh~r point, the urcr can edtt chc 
rn~r~alnrcd 
rtrlng or accept rr as It Ir by prcrrlng the RElVRN key However, tf the 
- 
~ntr~rltrrd 
omnr! conrams a mum. C7RL-M. or a Imcfeed. CTRL-I. character. Func- 
- 
. 
.. 


tian 10 retoms to the calling program without grv~ng the uwr the oppomnity to edit 
the s h g . 


The level of console editin. su~oorted bv Function 10 differs for the banked and 


nonhankrd urruonr of CP ~ ' j . 
difcr to rh; CP M Plus (CP M Vt~rmn 3, Operohng 


System Urn's Gutde for a dctatlrd drrcnption of conrolc edmng. In the nonbanked 
vcrs~on. Funaton 10 rrmgnrrrr the cdnr control characters rummar~ud m lahle 3.2. 


Table 3-2. Edit Control C h u p n m (Normbanked CP/M 3) 


1 Chnrocur 
I 
Edit Connol Fundon 
I 


CTRL-E 


CTRL-H 


Removes and echoes the last character; GENCPM can change 
this function to CTRL-H 


Rebwo when at the beginning of Line, the Console Mode can 
dlsable this function 


Causes physical end of linc 


Backspaces one character positron; GENCPM can change this 
function to rubldel 


(Line-feed) terminates input linc 


(Return) terminates input lrne 


Echoes console output to the list dcvicc 


Retypes the current line a h r new line 


Removes current line after new line 


Backpaces to beginning of ourcent line 


- 
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The banked version of CP/M 3 expands upon the editing provided in the non- 


banked version. The functionality of the two versions is similar when the cursor is 
positioned at the end of the line. However, in the banked version, the user can move 
the cursor anywhere in the current Imc, insert characters, delete characters, and 
perform other editing functions. In addition, the banked version saves the previous 
mmmand linc; it can be recalled when the current line rs empty. Table 3-3 summa- 
rizes the edit control characters supported by Function 10 in the banked version of 
CP/M 3. 


Table 3-3. Edit Contml Chpraners (Banked CP/M 3) 


Chardcter 
/ 
Edit Control Function 


rubldel 
Removes and echoes the last character if at the end of the line; 
otherwise deletes the character to the left of the current cursor 
position; GENCPM c m change this function m CTRL-H. 


I CTaL-A 
Moves cursor one character to the left. 


1 C R L B 
Moves cunor to the beginning of the I 
when not at the begin. 


ning; otherwise moves cursor to the end of the line. 


1 CTRLC 
Reboots when n the beginning of lime the Conmk Made un 
disable this function. 


CTaLE 
Causes physical end-of-linc; if the cursor is positioned in the 
middle of a line, the characters at and to the right of the cursor 
are displayed on the n u t linc. 


( CTRL-F 
Moves cursor one character to the right. 


1 _(i 


Deletes the iharactet at the current cursor position when in the I - 
mlddle of the linc; has no effect when the cursor is a the end of 
I 
the line. 
I 


CTRL-H 
Backspacer one character position when positioned at the end 
of the linc; otherwise dclcnr the character to the left of the 
cursor; GENCPM can change this function to rubldd. 


- 
- 
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- 
Table 3-3. (condnued) 


I Charactm 
I 
Edit Conhol Fundon 
I 


I 


vioua line buffer to the input line. 
I 
- 


CTRL-K 
Deletes all characters to the right of the cursor along with the 
character at the cursor. 


CTRL-J 
(Lme-feed) terminates mput; the cursor can be positioned any- 
where in the line; the entire input line is accepted; ws the prc- 


CIRL-M 
(Remn) terminates input; the cursor can be positioned any- 
where in the line; the entire input linc is accepted; sets the pre 
vious line buffer to the input line. 


CTRL-P 
Echoes console output m the list device. 
I 


CTRLR 
Retypes the characters to the left of the cursor on the new line. 
- I 


CTRL-U 
Updates the prcvious line buffer to contain the characters to the 
left of the cursor; deletes current line, and advances to new line. 


CTRL-W 
Recalls previous line if Nrrcnt line is empty; otherwise moves 
cursor to end-of-line. 


CTRLX 
Deletes all characten to the left of the cursor. 


For banked systems, Function 10 use* the consolc width field dcfincd in the System 
Control Block. If the mnsolc width is exceeded when the cursor is positioned at the 
end of the line, Function 10 automatically advances to the next linc. The beginning 
of the line can be edited by entering a CTRL-R. 


When a character is typed while the cursor is positioned m the middle of the linc, 


the typed character is inserted into the linc. Characters at and to the right of the 
cursor arc shiftcd to the right. If the console width is exceeded, the characters disap- 
pear off the right of the screen. However, these characters are not lost. They reappear 
if characters are deleted out of the line, or if a CTRL-E is typed. 
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Register C: OBH 


Returned Value: 
Register A: Console Status 


The Get Console Status fundon checks m see if a character has been ryped at 


the logical console, CONIN:. If the Console Mode is in the default state (se 
Section 2.2.1), Function 11 returns the valuc 01H in register A when a character is 
ready. If a character is not ready, it returns a valuc of DOH. 


If the Console Mode is in CTRL-C Only Status mode, Function 11 returns the 
value 01H in register A only if a CTRL-C has bccn w e d at the console. 


- 
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Register C: OCH 


Returned Value: 


Register HL: Version Number 


- 
The Return Version Numb" function provides information rhat allows version 


independent programming. It returns a two-bw value in e s t e r pair HL: H con- 
tains OOH for CP/M and L contains 31H, the BDOS file system version number. 
Function 12 is useful for writing applications programs that must run on multiple 
- 
versions of CP/M and MPIM. 


- 
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BDOS FUNCTION 13: RESET DISK SYSTEM 


Entry Parameters: 


Register C: ODH 


The Reset Disk System function restores the Plc system to a reset state where all 
the disk drives are set to read-write (see Functions 28 and 29), the default disk is set 
to drtve A. and the default DMA address is reset to 0080H. This function can be 
- -~ ~~. 
used, for example, by an application program that requires disk changes durlng 
operation. Fundon 37, Reset Drive, can also be used for this purpose. 


- CP/M 3 Programmer's Guidc 
3 BDOS Calls: Function 14 


Entry Parameters: 
Registers C: OEH 
E: Selected Disk 


- 


Returned Value: 
Registers A: Error Flag 


H: Physical Error 


BDOS FUNCTION 14: SELECT DISK 


The Select Disk function designates the disk drive named in register E as the 
default disk for subsequent BDOS file operations. Registcr E is set to 0 for drive A, 
1 for drive B, and so on through 15 for drive Pin a full 16-dnve system. In addluon, 
Function 14 logs in the designated drive if it is currently in the reset state. Logging- 
in a drive acuvates the drive's directory until the n u t disk system rcset or drive rcset 
operation. 


FCBs that speci* drive code zero (dr = OOH) automatically reference the currently 


selected default drive. FCBr with drive code values between 1 and 16, however, 
Ignore the selected default drive and directly reference drives A through P. 


Upon return, register A contains a zero if the select operation was successful. If a 
physical error was encountered, the select function perfonns different acuons depend- 
ing on the BDOS error mode (see Function 45). If the BDOS error mode is in the 
default mode, a masage identifying the error is displayed at the console, and the 
calling program is ruminated. Othenurse, the sdect funmon returns to the calhng 
program with register A set to OFFH and register H set to one of the following 
physical error codes: 


01 : Disk UO Error 
04 : Invalid drive 
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BDOS FUNCIlON 15: OPEN FILE 


Entry Parameters: 
Registers C: OFH 
DE: FCB Address 


Rrmmed Value: 
Registers A: Directory Code 
H: Physical or Extended Ermr -1 
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- 
- 
- 
- 


The Oocn File function activates the FCB for a file that exists in the disk directory 


under th; currently active user number or uMr xro. The calling program passes the 
address of the FCB in register pair DE, with byte 0 of the FCB specifying the drive, 
bnes 1 throueh 11 s~ecihr~ne 
the filename and fil-, 
and bvrc 12 s~ecihiinn the 
. . 
- 


c&ent. ~suall;, byte i 2 oith; FCB is initialized to &ro. 


If the file is password protected in Read mode, the wrrcn password must be 


placed in the first eight bytes of the m m t DMA, or have bem previously cstab- 
lished as the default password (see Function 106). If the current record field of the 
FCB, cr, is set to OFFH, Function 15 returns the byte wunt of the last m r d of the 
file in the cr field. You can set the last record byte count for a file with Function 30, 
Set File Attributes. Note that the current m r d field of the FCB, cr, must be zeroed 
by the calling program before beginning read or write operations if the file is to be 
accessed requentlally from the fint record. 


If the current user is "on-zero, and the file to be opmed does not exist under the 
current user number, the open hnnlon search- user zero for the file. If the file exists 
under user m, 
and has the system attribute, f2', set, the file is opened under uwr 


zero. Write operations arc not supported for a file that is opened under user zero in 
this manner. 
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- 
If the open operation is successful, the user's FCB is activated for read and write 


operations. The relevant directory information is copied from the match~ng directory 
FCB into bytes do through dn of the FCB. If the file is opmed under user zero when 
- 
the current user numbcr is not zero, interface attribute f8' e set to one in the user's 
FCB. h addition, if the refermad file is password protected in Write mode, and the 
c o r m password war not passed m the DMA, or did not match the default pass- 
word, interface attribute n' is set m one. Write opcratlons are not supported for an 
- 
activated FCB rf intedace attribute n' or 18' is w e . 


When the open operation is aumssful, the open function also makes an Access 
- 
date and ume stamp for the opened file when the following conditions are satisfied: 
the referenced drive has a directory label that requests Acccss date and time stamp- 
ing, and the FCB u t m t numbcr field is zuo. 
- 
Upon return, the Open Filc function r e m s a directory code in register A with the 


value OOH if the opm was sucassful, or FFH, 255 decimal, if the file was not found. 
Reeister H ia set to zero in both of these cases. If a ~hvrical or cxtcndcd error was 
- 
encountered, the Open File funaton performs diffeicnt actions depending on the 
BDOS crror modc lsce Function 45). If the BDOS error modc is in the default mode. 
r, messam identifvinc the error is disolaved at the console and the oroeram is temi- 
" 
. " 
. , 
. - 
- 
narcd. Olhrrwsc, the Open F~le funct~on returns to the call~ng program warh rc@rtcr 
A rrt to UFM, and rcplstcr H set to one of the followtng phyrtul or cxtcndcd crror 


- 
01 : Disk 110 Error 
04 : Invalid drive error 
07 : Filc password error 
- 
09 : ? in the FCB filmame or filctypc field 


- 
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Registers C: lOH 


DE: FCB Address 


Returned Value: 
Registers A: Directory Code 
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- 
- 
- 
- 


The Close File function performs the inverse of the Open File function. The calling 
program passe the address of an FCB in reemr pair DE. The referenced FCB must 
have been prev~ousl~ 
activated by a successful Open or Make function call (see 


Functions 15 and 22). Interface attrlbun f S specifier how the file is to be dosed as 
shown below: 


f S = 0 - Permanent dose (default mode) 
f S = 1 - Panlal close 


A permanent dose operation indicates that the program has completed file operations 
on the file. A partial close operation updates the directory, but ~ndicates that the file 
is to be maintained m the open state. 


If the referenced FCR conralns new lnformanon bccaure of wntr opcranonr ro rhc 


FCB, the r1o.c 
functton permanently records rhc new ~nformauon !n rhc rcfcrrnrrd 


disk d~rectorv. Notc that the FCB docs nor ronrarn new mfomar~un, and rhc dlrec- 
tory update step e bypassed d only read or update operations have been made to the 
referenced FCB. 
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Upon return, the close function returns a directory code in mglsvr A with the 
value OOH if the dose was successful, or FFH, 255 Deumal, rf the file was not found. 
Register H is set to zero in both of these cases. If a physical or extended error is 
encountered, the dose function performs different actions depending on the BDOS 
error mode (see Function 45). If the BDOS error mode is in the default mode. a 
message identtfytng the error is displayed at the console, and the calling 
is 


termmated. Otherwise, the close funnlon returns to the calling program with reglrvr 
A set to OFFH and register H set to one of the follow~ng physical error codes: 


01 : Disk UO error 
02 : Readtonly dlsk 
04 : Invalid drive error 
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Reglsters C: 11H 


DE: FCB Address 


Reamed Value: 
Registers A: Dlrcctory Code 


- 


'Ihc Search For Fmt function scans the direwry for a match with the FCB ad* 


by register pair DE. Two types of searches can be performed. For standard searches, 
the calling program initializes bytes 0 through 12 of the referenced FCB, with byte 0 - 
specifying the drive directory to be searched, bytes 1 through 11 specifying the file or 
files to be searched for, and byte 12 specifying the extent. Usually byte 12 is set to 
zero. An ASCII qucsnon mark, 63 decimal, 3F hex, many of the bytes 1 through 12 
matches all entries on the d~rcctory ~n the corresponding posaion. This facility, called - 


ambtguous reference, can be used to search for multiple files on the directory. \Wen 
called in the standard mode, the Search function scans for the fint file entry in the 
rpcc~fied directory that matches the FCB, and belongs to the current user number. 
- 


'Ihe Search For Fint function also lnltializcs the Search For Next function. After 
the Search function has located the fint directory entry matchmg the referenced FCB, 
the Search For Next function can be called repeatedly to locate all remaining match- - 


ing entries. In tennr of execution sequence, however, the Search For Next call must 
c~thcr follow a Search For First or Search For Next call with no other intervening 
BDOS disk-related function calls. 
- 


If byte 0 of the referenced FCB is set to a question mark, the Search function 
ignores the remainder of the referenced FCB, and locates the first directory entry - 
resldlng on the current default drive. All remaining directory entries can be located 
by making multiple Search For Next calls. Thns type of search operation is not 
usually made by application programs, but it does provide complete flexibility to 
scan all current d~rectory values. Note that this rgpe of search opcation must be 
- 


performed to access a dnve's directory label (see Section 2.3.6). 
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- 
Upon return, the Search function returns a Directory Code in register A with the 
value 0 to 3 if the search is successful, or OFFH, 255 Decimal, if a matchxng directory 
entry IS nor found Register H is set to zero in both of these cases. For successful 
searches, the current DMA is also filled with the directory record containing the 
- matching entry, and the mlauve starting position rs A ' 32 (that is, rotate the A 


regster left 5 bits, or ADD A k e times). Although it is not usually required for 
application programs, the dlrectory information can be mracted from the buffer at 
- this position. 


If the directory has been initialized for dare and time stamping by INITDIR, then 
- an SFCB resider in every fourth directory entry, and successful Directory Codes arc 


restricted to the values 0 to 2. For successful searches, if the matching directory 
record IS an extent zero entry, and d an SFCB resides at offset 96 within the curmnt 
DMA, contents of (DMA Address + 96) = 21H, the SFCB contams the date and 
- time stamo information. and assw word mode for the file. 'Ihls informatron is located 
~- 
at the relative starring position of 97 + (A ' 10) within the current DMA in the 
following format: 
- 
0 - 3 : Create or Access Date and Time Stamp Ficld 
4 - 7 : Update Date and Time Stamp Ficld 
8 : 
Password Mode Field 
- 


(Rekr to Section 2.3.8 for more information on SFCBs.) 


- 
If a physical error is encountered, the Search function performs different actions 


depmdrng on the BDOS error mode (see Function 45). If the BDOS error mode is in 
the default mode, a message identifying the crmr is displayed at the console, and the 
calling program is terminated. Otherwise, the Search function returns to the calling 
- 
program wtth register A set to OFFH, and register H set to one of the following 
physical error codes: 
- 
01 : Disk VO error 
04 : Invalid drwe error 
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Entry Parameters: 


Reester C: 1ZH 


BDOS FUNCnON 18: SEARCH FOR NEXT 
- 


The Search For Next function e >dentical to the Search For First function, except - 


that the d~rectory scan continues from the last entry that was matched. Function 18 
returns a Directory code m reester A, analogous to Function 17. 


Returned Value: 
Registers A: Directory Code 


H: Physical Error 


Note: ,n exearlon rcqucncr, a Funclnon 18 call must follow cnrhrr a tunmon 17 or - 


another tunrttun 18 call wtth no orhcr rntcrvcn~ng RDOS dlrk-rrlatcd funcrlon calls. 


- 
- 


- 
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Entry Parameters: 


Registen C: 13H 
DE: FCB Address 


- 


Returned Value: 
Registers A: Directory Code 
H: Extended or Physical Error 


BDOS FUNCTION 19: DELETE FILE 


- 


The Delete Ftle function removes files or XFCBs that match the FCB addressed in 


register pan DE. The filename and filetypc can contain ambiguous references, that is, 
- 
question marks m bytes fl through t3, but the dr byte cannot be ambiguous, as it 
can in the Search and Search Next functions. Interface antibute f5' specifies the type 
of delete operation that a performed. 
- 
f5' = 0 - Standard Delete (default mode) 
f5' = 1 - Dclctc only XFCBs 


- 
If any of the files that the rcfcrcnccd FCB rpccmfy arc parsword protected. the correct 
password must be placed m the firlt rlghr hyrcs of the current UhlA huffcr, or have 
been prcvlously caahl~shcd rr the default parsword ,N Funcuon 106 . 
- 
For standard delete operations, the Delete function removes all directory entries 


belongng to files that match the referenced FCB. All disk directory and data space 
owned by the deleted files is m r n e d to free spaa, and becomes available for allo- 
- 
cation to other filer. Directory XFCBs that were owned by the deleted files are also 
removed from the directory. If interface antibute f5' of the FCB IS set to 1, Functton 
19 deletes only the directory XFCBs that match the referenced FCB. 
- 
Note: ~f any of the files that match the input FCB specification far1 the password 
check, or arc Read-Only, then the Delete functton docs nor delete any filer or XFCBs. 
This applies to both types of delete opcratlons. 
- 
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In nonbanked systems, file passwords and XFCBs are not supported. Thus, d the 


Delete function is called with interface amibute fS set to true, the Delete function 
performs no aaion but returns with register A set to zero. 


Upon return, the Delete function returns a Directory Code in register A with the 


value 0 if the delete is successful, or OFFH, 255 Decimal, if no file that matches the 
referenced FCB is found. Register H is set to zero in both of these cases. If a physical, 
or extended error a encountered, the Delete function performs different actions 
depending on the BDOS error mode (see Function 45). If the BDOS error mode is 
rhc default mode, a marage bdcnttfying the error is displayed at the console and the 
calling program a terminated. Otherwise, the Delete fvnction returns to the call~ng 
progrsm wnth register A set to OFFH and register H set to one of the following 
physical or extended error codes: 


01 : Disk UO error 
02 : Read-Only disk 
03 : Read-Only file 
04 : Invalid drive e m r 
07 : File password error 
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Registem C: 14H 
DE: FCB Address 


Returned Value: 


Registea 
A: Ermr Code 


The Read Sequential function mads the n u t 1 to 128 128-byte records from a file 


into memory beginning at the cumnt DMA address. Thc BDOS Multr-Sector Count 
(scr Function 44) determiner the number of records to be read. The default is one 
record. The FCB addmwd by register pair DE must have been previously activated 
by an Open or Make function call. 


Function 20 reads each record from byte cr of the extent, then automatically 


increments the cr field to the n u t record position. If the u field overflows, then the 
function automatically opma the n u t logical extent and msea the cr field to 0 m 
preparation for the next read operation. The calling program must set the cr field to 
0 following the Open a l l if the intent is to mad sequentially from the beginntng of 
the file. 


Upon r a m , the Read Sequential function sets register A to zero if the read oper- 
ation is mcmsful. Othenulse, rcgrster A contains an error code identifying the error 
as shown below: 


01 : Reading unwrinen data (end-of-file) 
09 : Invalid FCB 
10 : Media change occurred 


255 : Physical Error; refer to register H 
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Error Code 01 is returned tf no data cxlstr at the next record position of the file. 
Usually, the no data situation is encountered at the end of a file. However, it can 
also occur if an attempt 1s made to read a data block that has not been previously 
wntren, or an went which has not been created. Thae situations are usually resrncted 
to filer created or appended with the BDOS random write functions (see Functions 
34 and 40). 


Error Code 09 is returned 11 the FCBis invalidated by a prevtousBDOS close call that 


rerurns an error. 


Error Code 10 is returned if a media change occurs on the drive after the refer- 
enced FCB e activated by a BDOS Open, or Make Call. 


Error Code 255 is returned if a physical error is encountered and the BDOS error 
mode is Return Error mode, or Return and Dwplay Error mode (see Function 451. If 
the error mode is the default mode, a message identifying the physical error is dis- 
played at the console, and the calling program is terminated. Wlen a physical error 
e returned to the callmg program, register H contains one of the following error 
codes: 


01 : Disk 110 crmr 
04 : Invalid drive ermr 


On all error returns exccot for ohvsical error returns. A = 255. Function 20 sets 
. 
. . 


register H to the number of records succesrfully read before the error 1s encountered. 
Th~s value can range from 0 to 127 depend~ng on the current BDOS Multi-Sector 
Count. It is always set to zero when the Multi-Sector Count is equal to one. 
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Registen C: 1SH 


DE: FCB Address 


Returned Value: 


Registen 
A: Error Code 


- 


The Write Sequentla1 function writes 1 to 128 128-byte data records, beginning at 
the current DMA address into the file named by the FCB addressed in register pair 
- 
DE. The BDOS Multr-Sector Count (see Function 44) determines the number of 128 
byte records that are written. The default rs one record. The referenced FCB must 
have been previously activated by a BDOS Open or Make function call. 
- 
Function 21 places the remrd into the file at the position indicated by the cr byte 
of the FCB, and then automatically Increments the er byte to the n u t record pon- 
tion. If the cr field overflows, the function automatically opens, or creates the next 
- 
logical extent, and resets the cr ficld to 0 in preparation for the next write operation. 
If Function 21 is used to write to an existing file, then the newly wrimn records 
overlay those already existing in the file. The calling program must set the cr ficld to 
- 
0 following an Open or Make a l l if thc intat a to write sequentially from the 
beginning of the file. 


Funn~on 21 maker an Update date and nmc Lor rhc file tf the follawnnp condrnonr 
- 
arc sarnrficd the referenced drlvc has a d~rccrory label thal rrqunrs dare and nme 
srarnplng, and the file has nor already hccn stamped for updatc hy a prcvlour .Makc 
or Wnre function call. 
- 
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Upon return, the Write Sequential function sets rwster A to zero if the write 
operation a successful. Othcrwae, register A contains an ermr code ~dentifying the 
error as shown below: 


01 : No available directory space 
02 : No available data block 
09 : Invalid FCB 
10 : Mcdla change occurred 


255 : Physical Error : refer to register H 


Error Code 01 a r e w e d when the write function attempts to create a new extent 
that requires a nnu directory entry, and no available directory enmes exist on the 
selected disk drive. 


Error Code 02 is returned when the write command attempts to allocate a new 
data block to the file, and no unalloutcd data blocks exist on the selected disk drive. 


Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call 
that returns an error. 


Error Code 10 is murned if a media change occurs on the drive after the refer- 


enad PCB is activated by a BDOS Open or Make call. 


CP/M 3 Programmcr'r Guide 
3 BDOS Calls: Function 21 


Error Code 255 is returned if a physical error is encountered and the BDOS error 
mode is Return Error mode, or Return and Dtsplay Error mode (see Function 45). If 
the error mode rs the default mode, a message idenufying the physical error is dis- 
plqed at the conrole, and the calling program rs tcmmated. When a physical error 
is returned to the calling program, register H contains one of the following error 
codes: 


01 : Disk 110 error 
02 : Read-Only disk 
03 : Read-Only file or 


File open from user 0 when 
the current user number is non-zero or 
Flle password protected in Write mode 
04 : Invalid drive error 


On all error returns, except for physical ermr rrmrna, A = 255, Function 21 sets 


register H to the number of records succcasfully wdcten before the error was encoun- 
tered. This value can range from 0 to 127 depending on the current BDOS Multi- 
Sector Count. It is always set to zero when the Multl-Senor Count rs set to one. 
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- 


Registers C: 16H 
DE: FCB Address 


Returned Value: 


Registers A: D~mctory Code 


- 


The Make File function creates a new directory entry for a file under the current 


user number. It also creates an XFCB for the file d the referenced drwe has a direc- 
tory label that enables password protmion on the dnvc, and the call~ng program - 
assigns a password to the file. 


The calling program passes the add- 
of the FCB in register p a r DE, with byte 0 


of the FCB specifying the drive, bytes 1 through 11 specifying the filename and - 
filetype, and byte 12 set to the extent number. Usually, byte 12 8s set to zero. Byte 
32 of the FCB, the cr field, must be iniriallred to zero, before or a h r rhc Make call, 
if the Intent is to write sequentially from the beginning of the file. 
- 


Interface attribute f6' specifies whether a password is to be assigned to the created 
file. 
- 


f6' = 0 - Do nor assign password (dchult) 
f6' = 1 - Assign 
to created file 
- 


When attribute f6' is x t to 1, the calling program must place the password ~n the 
first 8 bytes of the current DMA buffer, and set byte 9 of the DMA buffer to the 
password mode (see Function 102). Note that the Make function only interrogates - 
interface attribute f6' if passwords are activated on the referenced dnve. In non- 
banked systems, file passwords are not supported, and ambute f6' is never interrogated. 


nlhc Makc functian r r ~ r n s with an error if the referenced FCB names a file that - 


currently exisn in the directory under the current user number. 
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If the Make tunctton s successhl, a amvarer the referenced FCB for file opera- 
tions by opening the FCB, and initializes both the dtrenory entry and the referenced 
FCB to an empty file. It also lnitlalizer all file attributes to zero. In addition, Function 
22 makes a Creation date and time stamp for the file if the following conditions are 
satisfied: the referenced drive has a directory label that requests Creation date and 
time Etarnprng and the FCB utent number field a equal to zero. Function 22 also 
makes an Update stamp if the directory label requests update stamping and the FCB 
utent field is equal to zero. 


If rhe referenced drive contams a directory label that enables password protection, 
and tf interface attr~butc f6' has been set to 1, the Make function creates an XFCB 
for the file. In addition, Funaton 22 also assrgns the password, and password modc 
placed in the first nlne bpes of the DMA, to the XFCB. 


Upon return, the Make function returns a directory code in reester A wtrh the 


value 0 ~f the make operation rs successful, or OFFH, 255 decimal, if no directory 
space is avadablc. Register H is set to zero in both of these cases. If a physical or 
cxtendd error is encountered, the Make function performs different actions depend- 
mg on the BDOS error mode (see Function 45). If the BDOS error modc is the 
default mode. a messaee identifvine the error is disolaved at the mnsole. and the 
.. 
. . . 
. , 


call~np prup,ram Is lrrmmatcd. Othcnulw, the Makr hnctnon m r n r tu rhc cnllmg 
program w ~ r h rcglrrcr A rct ro OFFH, and rcyscr H set to one of the follow~n~ 
phys~cnl or cxrrndcd error coder: 


01 : Disk VO error 
02 : Read-Only drrk 
04 : Invalid drive error 
08 : Fie already exists 
09 : ? in filename or filetype field 
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BDOS FUNCllON 23: RENAME FILE 


Entry Parameters: 


Regsters C: 17H 
DE: FCB Address 


Returned Value: 


Registers A: Directory Code 
H: Physical or Extended Error 


The Rename function uses the FCB, addresxd by mglrter pair DE, m change all 
directory entries of the file specified by the filename in the first 16 bytes of the FCB 
to the filename m the second 16 bytes. If the file specified by the first filmame is 
password protected, the correct password must be placed in the first eight bytes of 
the current DMA buffer, or have been 
established as the default password 


(see Function 106). The calling program must also ensure that the filenames speclficd 
in the FCB are vahd and unambiguous, and that the new filename docs not already 
exist on the drive. Function 23 uses the dr code at byte 0 of rhc FCB to select the 
drive. 'Ihe drive code at byte 16 of the FCB is ~gnored. 
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Upon mum, the Rrnamc bncnon mums a Uhmctory Lode m rcgrtcr A wnrh the 


value 0 11 the rcnamc Ir rucccroful, or OFFH, 255 Ucc~mal, ~f the file named by rhc 
finr filename ~n the FCB rr nor found Reerrcr H Ism to rrru ~n hoth of rhcvc clrrs 
If a physical or extended error is encountered, the Rename function perfoms differ- 
ent actions depending on the BDOS error mode (see Function 45). If the BDOS error 
mode 1s the default mode, a message identifying the error is displayed at the console 
and the program is terminated. Othenulre, the Rename function returns to the calling 
program with regrster A set to OFFH and register H set to one of the following 
physical or extended error codes: 


01 : Disk UO error 
02 : Read-Only dxsk 
03 : Read-Only file 
04 : Invalid drive error 
07 : File password error 
08 : Fdc already exists 
09 : ? in filename or fil- 
field 
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Register C: 18H 


Returned Value: 


Fundon 24 m u m s the login vmor m register pair HL. The login vector is a 16- 


bit value with the least significant bit of L corresponding to drive A, and the high- 
order bit of H corrcspanding to the 16th drive, labelled P. A 0 bit indicates that the 
drive is not on-line, while a 1 bit indicates the drivc is active. A drive is made a&e 
by either an exphcit BDOS Select Disk call, number 14, or ur impllcit sclcdon when 
a BDOS file operation specifics a momzero dr byte in the FCB. Function 24 maintains 
compatibilty with eadier releases since registers A and L contain the same values 
upon return. 


- 
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Enay Parameters: 
Register C: 19H 


- 


/ 
RmmgzE 
k Current Disk 


BDOS FUNCTION 25: RETURN CURRENT DISK 


Function 25 returns the currently selected default disk number in register A. The 
- 
disk numbers range from 0 through IS corresponding to drives A through P. 
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Entry Parameters: 


Rcgtsterr C: 1AH 


DE: DMA Address 


BDOS FUNCTION 26: SET DMA ADDRESS 


DMA 1s an acronym for Direct Memory Address, which is often used m connec- 


rton wlth dirk controllers that directly access the memory of the computer to transfer 
data to and from the disk subsystem. Under CP/M 3, the current DMA a usually 
defined as the buffer in memory where a record resides before a disk write, and after 
a disk read operation. If the BDOS Multl-Sector Count is equal to one (see Function 
44), the sire of the buffer is 128 bytes. However, if the BDOS Multi-Sector Count is 
greater than one, the stze of the buffer must equal N ' 128, where N equals the 
Muln-Sector Count. 


- 


Some BDOS functtonr also use the current DMA to pass parameters, and to return 
valuer. For example, BDOS hndons that check and assign file passwords require 
that the password be placed I" the current DMA. I\J another example, Function 46, 
Get Dirk Free Space, returns its results m the first 3 bytes of the current DMA. When 
the current DMA is used in thls context, the snre of the buffer m memory is deter- 
m~ned by the specific requirements of the called function. 


When a translent program is nnitlatcd by the CCP, its DMA address is set to 


0080H. The BDOS Reset Disk System function, Function 13, also sets the DMA 
address to 0080H. The Set DMA function can change this default value to another 
memory address. The DMA address is a t to the value pasad in the reglstcr pair DE. 
The DMA address remains at this value until it is changed by another Set DMA 
Address, or Reset Disk System call. 
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BDOS FUNCnON 27: GET ADDR(ALL0C) 


I 
~ n t r y 
Parameters: 
Register C: 1BH 


I 
Reurned Value 


Register HL: ALLOC A d d m 


CP/M 3 maintains an sllocation vmor in main memoo. for each actwe disk drive. 


Some programs use the informatton provrded by the allocation vector to determine 
the amount of free data space on a drive. Note, however, chat the allocation infor- 
mation might be inaccurate if the drive has been marked Read-Only. 


Funltlon 27 r a m s m reester pair HL, the base address of the allocation vector 
for the currently selected drive. If a physical error is encountered when the BDOS 
error made is one of the return modes (see Function 45), Function 27 returns rhe 
value OFFFFH in the register pair HL. 


In banked CPlM 3 systems, the allocatron vector can be placed in bank zero. In 
this case, a transient program cannot acmr the allocation vector. However, the 
BDOS function, Get Disk Free Space (Function 46), can be used to directly return 
the number of free 128-byte records on a drive. The CP/M 3 utilities that display a 
dnve's free space, DIR and SHOW, use Function 46 for that purpose. 
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BDOS FUNCTION 28: WRITE PROTECT DISK 


Entry Parameters: 


Register C: ICH 


The Wnte Protect Dlsk function provides temporary write protection for the cur- 
rently selected disk by marktng the drwe as Read-Only. No pmgrarn can write to a 
dlsk that is in the Read-Only stare. A drive reset operation must be performed for a 
Read-Only drwe to restore a to the Read-Write stare (see Functions 13 and 37). 
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Register C: 1DH 


Returned Value: 


Fundon 29 returns a bit vector in register pair HL that indicates which drives 
- 
have the temporary Read-Only bit set. fie Read-Only bit can be set only by a BDOS 
Wrrtc Protect Disk call. 


- 
'IIe brmat of the bit vector is analagous to that of the login vector returned by 


Function 24. 'X%e least figolficant bit corresponds to drive A, while the most signifi- 
cant bit cornsponds to drive P. 


- 
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Enny Parameten: 


Registers C: IEH 
DE: FCB Address 


BDOS FUNCTION 30: SET FILE ATTRIBUTES 


Rrmmed Value: 


Registers A: Directory Code 
H: Physical or Extended error 


- 


7 


By calling the Set Fllc Attributes function, a program can modify a file's attributes 
and sn m last record byte count. Other BDOS functions can be called to Interrogate 
these file parameten, bur only Function 30 can change them. The file attributes that 
can be set or reset by Funaion 30 are fl' through f4', Read-Only, tl', System, t2', - 


and Archive, t3'. The register pair DE addresses an FCB containing a filename with 
the appropriate attributes set or reset. The calling program must ensure that it docs 
not specify an amb~guous filename. In addition, if the specified file is password pro- - 
teaed, the mrrca password must be placed m the first eight bytes of the current 
DMA buffer or have been previously established as the default password (see Func- 
tion 106). 
7 


Interface amibute f6' specifies whether the last remrd byte munt of the specified 


file is to be set: 
- 


f6' = 0 - Do not set byte count (default mode) 
f6' = 1 - Set byte counr 
- 


If ~nrrrfacc attnhurc f6' IS set. thc calling program must set the cr field of the refer- 
cnccd F(:B t o rhc byte count valuc. A program can aiccrr a file'\ hyrc count value 
wah the HDO\ Open. Scarch, or Scarch Ncxr funa!onr. 
- 


Function 30 searches the referenced dxreaory for entries belonging to the current 
user number that matches the FCB specified name and type fields. The function then 
updates the directory to contain the selected indicators, and if interface attribute f6' - 
is set, the ~peclfied byte munt value. Note that the last rcmrd bytc count 1s ma,"- 
tained in bytc 13 of a file's dlrectary FCBs. 
- 
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File attributes tl', tT, and t3' arc defined by CP/M 3. (They are described in 
Section 2.3.4.) Attributes fl' through f4' are not presently used, but can be useful for 
application programs, because they are not involved in the matching pmgram used 
by the BDOS durrng Open File and Close File operatrons. lndlcators f S through f8' 
arc reserved for use as lnrcrface attributes. 


Upon rerum. Funcnun 10 rmmr a Dnrrctury <ode ~n rcgrrcr A wnth the value 0 


~f the funcnon Is succerrful, or OttH. 255 Deomal. ~f the 6lc sprcnfied by rhc refer 
rnad FCB Br nor found Rtgrrtcr H tr set to zero ~n both of rhrrc CaKI If a phyrocal 
or extended error a encountered, the Set File Anr~butcs function performs different 
acdons depending on the BDOS error mode (we Function 45). If the BDOS error 
mode is the default mode, a message identiking the ermr is d~rplayed at the console, 
and the program is terminrod. Otherwise, Function 30 returns to the calling pro- 
gram with register A set to OFFH, and register H s a to one of the followrng physical 
or extended error codes: 


01 : Disk VO error 
02 : Read-Only disk 
04 : Selm error 
07 : File password error 
09 : ? m filename or fiktype field 
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Entry Parameters: 


Rcgl~ter C: 1FH 


BDOS FUNCTION 31: GET ADDR(DPB PARMS) 


Rrmrned Value: 
Register HL: DPB Address 


- 


Function 31 returns in register pair HL the address of the BIOS-resident Disk 


Parameter Block, DPB, for the currently selected drive. (Refer to the CPIM Pbs 
(CPIM Version 31 Operating System Syrtrm Guide for the format of the DPB). The 
calling program can use this address to extract the disk parameter values. 


If a physical error is encountered when the BDOS error mode is one of the rrmrn 


modes (see Function 49, Function 31 returns the value OFFFFH in the register palr 
HL. 


- 
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Envy Parameters: 


Registers C: 20H 


E: OFFH (get) or User Code (set) 


Rrmrncd Value: 


Regster A: Current Code or 


- 


A program can change, or interrogate the currently active user number by calling 


Functron 32. If register E = OFFH, then the value of the Nrrent user number is 
- 
returned in register A, where the value is in the range of 0 to IS. If register E is not 
OFFH, then the current user number IS changed to the value of E, modulo 16. 


- 
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Registers C: 21H 


DE: FCB Address 


Returned Value: 
Registers A: Error Code 


The Read Random function is similar to rhc Read Sequential function except that 


the read operation rakes place at a pamcular random record number, selected by the 
24-bit value constructed from the three byte, rO, rl, r2, field beginning at porltion 
33 of the FCB. Note that the sequence of 24 bits is stored with the least significant 
byte first, rO, the middle byte next, rl, and the high byte last, r2. The random record 
number can range from 0 to 262,143. Thls corresponds to a maximum value of 3 in 
bye r2. 


To read a file with Function 33, the calling program must first open the base 


extent, extent 0. This ensures that the FCB is properly initialized for subsequent 
random acass operations. The base extent may or may not contain any allocated 
data. Function 33 reads the record specified by the random record field into the 
current DMA address. The function automat~uilly sets the logical extent and current 
record valuer, hut unlike the Rcad Sequential function, it do= nor advance the 
current record number. Thus, a subsequent Read h d o m call rereads the same 
record. Ahcr a random read operation, a file can be accessed sequentially, starting 
from the current randomly accessed position. However, the last randomly accessed 
record 1s reread or w r m e n when switching from random to sequential mode. 


If the BDOS Multi-Sector Count is greater than one (see Function 44), the Rcad 


Random function reads multiple consecutive records mto memory beginning at the 
current DMA. The rO, rl, and r2 field of the FCB is automatically incremcnted to 
read each record. However, the FCBs random record number IS mtorcd to the first 
rccord's value upon remrn to the calling propm. 
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- 
Upon rrmrn, the Read Random function sets rcgisnr A to zero if the read opera- 
tion was successful. Othcnuise, register A contams one of the following error codes: 


01 : Reading unwritten data (end.of-file) 
- 
03 : Cannot dose current extent 
04 : Seek to unwritten extent 
06 : Random record number out of range 
- 
10 : Medm change occurred 
255 : Physical Error : refer to register H 


- 
Error Code 01 tr rrmrncd ~f no data exlrtr at thc next rccurd porttlon of the filr. 


11-"ally, tht no data ~~matnon 
a mcountcrcd at the end 01 a file. Howcvn, tt can 


also oLcur 11 an attempt Ir made to read a data hlock that ha, nor hccn preunou~ly 
written. 


Error Code 03 is returned when the Read Random function cannot dose the 
current extent prior to moving to a new extent. 


Error Code 04 is returned whcn a read random operation accesses an a n n t that 
has not been created. 


Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than 
3. 


Error Code 10 is returned if a media change occurs on the drive aher the refer- 
enced FCB is anlvated by a BDOS Open or Make Call. 


Error Code 255 1s returned if a physical error is encountered, and the BDOS error 
mode is one of the return modes (see Function 45). If the error mode is the default 
mode, a message identi*ng 
the phyacal e 
m 
a displayed at the console, and the 


call~ng program a terminated. When a physical error rs returned to the calling pro- 
gram, reester H contains one of the following error codes: 


01 : Disk 110 error 
04 : Invalid drive error 


On all enor returns except for physical errors, A = 255, the Read Random 
function sets register H to the number of records successfully read before the error a 
encountered. This value can range from 0 to 127 depending on the current BDOS 
Multi-Senor Count. It ir always set to rcm whcn the Multi-Senor Count is equal to 
one. 
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- 


BDOS FUNCTION 34: WRITE RANDOM 


Entry Parameters: 
Registers C: 22H 


DE: FCB Address 


Returned Value: 


Registers A: Error Code 
H: Physlcal Error 


The Write Random function is analogous to the Read Random funcuon, except 
that data is wrlnen to the disk from the current DMA address. If the dirk extent or 
data block where the data is to be written is not already allocated, the BDOS auto- 
matically performs the allocation before the write operation continuer. 


To wrwe to a filc using the Write Random function, the calling program must first 
open the base extent, extent 0. I h l r ensures that the FCB is properly mirlalizcd for 
subsequent random access operattons. If the file e empty, the calling program must 
create the base extent with the Make File function before calltng Function 34. The 
base extent might or mtght not contain any allocated data, but it does record the 61c 
in the directory, so that the file can be displayed by the DIR utihty. 


Ihe Write Random function rerr the logical extent and current record positions to 
correspond w~th the random record being wntten, but doer not change the random 
remrd number. Thus, sequential read or write operations can follow a random wnte, 
with the current record bang reread or rewritten as the calling program switches 
from random to scquentlal mode. 


Function 34 makes an Update date and tlme stamp for the file rf rhc following 


conditions are sansfied: the referenced drive has a directory label that requests Update 
date and tcme stamptng if the filc has nor already been stamped for update by a 
previous BDOS Make or Wrlte call. 
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- 
If the BDOS Multi-Sector Count is greater than one (see Function 44), the Write 
Random function reads multiple consccutivc records into memory beginning at the 
current DMA. The rO. rl. and r2 field of the FCB is automaricallv incremented to 
. , 


wrm each record. However. the FCB's random record number is revtored to the first 
- 
rcrord'v value when 11 return< to the rall~ng proyam Upon return, the \Y'nrc Ran- 
dom lunctaon XIS 
replster A to zero ~f the w r l t ~ operatmn IS IU.CC~<TUI. 
OI~CMISC, 


regxster A contains one of the following ermr coder: 


02 : No available data block 
03 : Cannot Close current extent 
05 : No available directory space 
06 : Random record number out of range 
10 : Media change occurred 
255 : Physical Error : refer to register H 


Error Code 02 is returned whcn the write command attempts to allocate a new 
data block to the file and no unallocatcd data blocks mist on the selected dlsk drive. 


Error Code 03 is returned whcn the Write Random function cannot dose the 
current cxnnt prior to movlng to a new ortent. 


Error Codc 05 is returned when the write funcdon attempts to create a new extent 
that requires a new drrectory entry and no avarlable directory entrtes exmt on the 
selected dirk drive. 


Error Code 06 is returned whcn bye 35, r2, of the referenced FCB is greater than 
3. 


Error Codc 10 is returned if a media change occurs on the drive aker the refer- 
enced FCB is acuvatcd by a BDOS Open or Make Call. 
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Error Code 255 is returned if a physical error is encountered and the BDOS error 
mode is one of the return modes (see Function 45). If the error mode is the default 
mode, a message ldentifying the physical error is displayed at the console, and the 
calhng program is temnated. When a physical error is returned to the calling pro- 
gram, it a identified by register H as shown below: 


01 : Disk UO error 
02 : Read-Only disk 
03 : Read.Only file or 
File open from user 0 when the current user number is nonzero or 
File parsward protected in Wrin mode 
04 : Invalid drive error 


On all error returns, except lor physxcal errors, A = 255, the Write Random 
function sns register H to the number of remrds successfully written before the error 
a encountered. This value can range from 0 to 127 depending on the curwnt BDOS 
Multi-Sector Count. It is always set to zero when the Muln-Sector Count is equal to 
one. 
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I 
BDOS FUNCTION 35: COMPUTE FILE SIZE 
( 


Entry Parameters: 
Registers C: 23H 


DE: FCB Address 


Returned Value: 
Registers A: Error Flag 
H: Physical or Extended error 


Random Record Field Set 


The Compute File Size function determiner the virtual file size, which is, in effect, 
the address of the record immediately followrng the end of the file. The virtual 
of a file corresponds to the physrcal size if the file is wrltten sequentially. If the file is 
written in random mode, gaps might emst in the allocation, and the file might con- 
tain fewer records than the lndlcated size. For example, 11 a single record with record 
number 262,143, the CP/M 3 max~mum is written to a file using the Wnte Random 
function, then the vimal srzc of the file is 262,144 records wen though only 1 data 
block is actually allocated 


To compute file are, the calling program passes in register pair DE the address of 
an FCB in random made format, bytes rO, rl and r2 present. Note that the ECB 
must contain an unamb~guous filename and filetype. Function 35 sets the random 
remrd field of the FCB to the random rccord number + 1 of rhe last record m the 
filc. If the r2 byte is set to 04, then the filc contains the maxtmum record count 
262,144. 


A program can appmd dam to the end of an casting file by calling Function 35 to 


set the random record ~osition to the end of file, and then performing a sequencz of 
random writes starting at the preset record address. 


Note: the BDOS docs not require that the file be open to use Function 35. However, 
$the Pe has been written to, it must be dosed before callmg Function 35. Other- 
wise, an incorrect file size might be returned. 
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Upon return, Funct~on 35 returns a zero in register A if the file specified by the 


referenced FCB IS found, or an OFFH in register A if the file is not found. Register H 
is set to zero in both of these cases. If a physical error is encountered, Function 35 
performs different anions depending on the BDOS error mode (see Function 45). 
If the BDOS error mode is the default mode, a message identifying the error is 
displayed at the console and the program a terminated. Otherwise, Function 35 
returns to the calling program with regtstcr A set to OFFH, and register H set to one 
of the following physical erron: 


01 : Disk 110 error 
04 : Invalid dr~ve error 
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Entry Parameters: 


Regrstcrs C: 24H 
DE: FCB Address 


- 


/ 
Returned Value: Random Remrd F~eld Set 


BDOS FUNCTION 36: SET RANDOM RECORD 


The Set Random Record function returns the random record number of the n u t 


remrd to be accessed ftom a filc that has been mad or written sequentially to a 
particular point. %is value is rrmrncd in the random rccord field, bytes t0, rl, and 
rZ, of the FCB addressed by the register pair DE. Function 36 can be useful in two 
ways. 


First, it is often necessary to inrtially read and scan a sequential file to exttact the 
positions of varlour key fields. As each key is enmuntcred, Function 36 a called to 
compute the random record posxtion for the data corresponding to this key. If the 
data unit size is 128 bytes, the resulting remrd numbcr mtnus one is placed into a 
table wlth the key for later mrieval. After scanning the entire file and tabulariring 
the keys and their record numbers, you can move directly to a particular record by 
performing a random read using the corresponding random record number that you 
saved earlier. The scheme is easily gemeralid when vanable mcord lengths am involved, 
because the program need only store the buffer-relative byte position along with the 
key and record number to find the uact stanlng pos~tlon of the keyed data at a later 
time. 


A second use of Function 36 occurs when switching from a sequential read or 
write over to random read or write. A file is sequent~ally accessed to a particular 
point in the file, then Function 36 is called to set the record number, and subsequent 
random read and wrlte operations continue kom the next record in the filc. 
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Registers C: ZSH 


DE: Drive Vector 


Returned Value: 
Register A: OOH 


The Reset Drive function prograrnmatxcally restores specified drives to the met 


state. A =set drive is not logged-in and is m Read-Wnu status. The passed parame- 
ter I" register pair DE is a 16-bit vecmr of drives m be reset, where the least sipifi- 
cant bit corresponds to the first drive A, and the high-order bit corresponds to the 
sutcenth drive, labelled P. Bit values of 1 indicate that the spedfied drnvc is to be 
met. 
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BDOS FUNCTION 38: ACCESS DRIVE 


Entry Parameters: 
Register C: 26H 


This is an MPIM funmion that is not supported under CP/M 3. If called, the file 


system t a r n s a zero m register A indicating that the access request is sucassful. 


3 
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- 


Thlr nr an UP .M hncrlon that Ir nor supported under CI'M 3. If wllcd, rhc file - 


system mrurns a zero m rcysrrr A lndncarlng that the hrc request IS ~ u r r r ~ ~ h l 
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BDOS FUNCTION 40: WRITE RANDOM WITH 
ZERO FILL 


Entry Parameters: 


Reglstcrs C: 28H 


DE: FCB address 


Returned Value: 


Registen 
A: Error Code 
H: Physical Error 


The Write Random With Zero Fill funelon is identical to the Write Random 
function (Function 34) wtth the exception that a previously unallocatcd data blodi is 
filled wirh zeros before the record is wnnen. If this function has been used to create 
a file, records accessed by a read random operation that mntain all zeros identify 
unwnmn random remrd numberr. Unwritten random mords in allmated data bl& 
of fiLs created using the Write Random funelon (Function 34) contain unrnitialized 
data. 
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BDOS FUNCTION 41: TEST AND WRITE RECORD 


Entry Parameters: 


Registerr C. 29H 
DE: FCB Address 


Returned Value: 


Registers A: Error Code 
H: Physical Error 


- 


The Test and Write Record funnlon a an MPiM 11" function that is not sup- 
ported under CP/M 3. If called, Function 41 returns with register A set to OFFH and 
reglrter H set to zero. 
- 
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Registers C: 2AH 


DE: FCB Address 


Rrmrned Value: 
Register A: OOH 


The Lo& Record function is an MPlM I1 function that is supported under CP/M 3 
only to provldc compatibility between CP/M 3 and MPIM. It is intended for use in 
situat~ons where more than one running program has Read.Writc access ro a com- 
mon file. Because CP/M 3 rs a single-user operating system in which only one pro- 
gram can run at a tlmc, this situation cannot occur. Thus, under CP/M 3, Functron 
42 performs no action except to return the value OOH in register A indlcattng that 
the record lock operation is succcsrful. 
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BDOS FUNCTION 43: UNLOCK RECORD 


Entry Parameters: 
Registers C: 2BH 


DE: FCB Address 


1 
R e t u d Value: 


Register A: OOH 


The Unlock Record function is an MPIM I1 function that is supported under 


CP/M 3 only to provide compatib!liry between CP/M 3 and MPIM. It is ,"tended for 
use m situations where more than one running program has Read-Write access to a 
common file. Because CP/M 3 a a smgle-user opcratxng system in which only one 
program can run at a tlme, this situation cannot occur. Thus, under CP/M 3, Func- 
tion 43 performs no action except to return the value OOH in register A indicating 
that the record unlock operation is successful. 
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Entry Paramems: 


Registers C: ZCH 


E: Number of Secton 


Rrmrncd Value: 
Register A: Return Code 


- 
The Sn Multr.Scctor Count hnctlon provldn logical record block~ng under 
CP M 3. It enabler a proyam ro read and wnre horn 1 to 128 rcmrdr of 128 bytes 
at a nmc dunng rubvqucnr BDOS Read and Wrnc hnctlonr 


Function 44 sets the Multi-Sector Count value for the calling progmrn to the value 
passed in reester E. Once set, the specified Multi-Smor Count remama in effect until 
the calling program makes another Set Multi-Seeror Count function call and changes 
the value. Note that the CCP sea the Multi-Senor Count to one when it initiates a 
transient program. 


The Multi-Sector Count affects BDOS error reporting for the BDOS Read and 
Write haions. If an m 
r 
~nDMpa thev functions whm rhe Multi-Sector is water 


than one, they return the number of records successfully read or written in register 
H for all errors except for phyrlcal erron (A = 255). 


Upon r a m , register A is set to zero d the specified value is in the range of 1 to 
128. Otherwise, register A is set to OFFH. 


3 BDOS Calls: Function 45 
CP/M 3 Programmer's Guidc 


Registers C: 2DH 


E: BDOS Error Mode 


Returned Value: None 


Function 45 sets the BDOS error mode for the calling program to the mode spcd- 


ficd m register E. If register E IS set to OFFH, 255 decimal, the c m r mode is set to 
Return Error mode. If register E is set m OFEH, 254 declmal, the ermr mode is set 
to Return and Display mode. If register E is set to any other value, the error mode is 
set to the default modc. 


The SET BDOS Error Mode function determines how physical and extended errors 


(see Senion 2.2.13) are handled for a program. The Error Mode can exist in three 
modes: the default mode, Return Error modc, and Return and Display Error mode. 
In the default mode, the BDOS displays a system message at the console that identi- 
fier the crror and terminates the calling program. In the return modes, the BDOS sets 
register A to OFFH, 255 decimal, places an error code that identtfics the physical or 
extended crror in register H and returns to the calling program. In Return and 
Display mode, the BDOS displays the system mesJage before returning to the calling 
proaram. No system messages ace displayed. however, when the BDOS a in Return 
Error mode 
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/ 
BDOS FUNCIlON 46: 
GET DISK FREE SPACE 
1 


Entry Parameters: 
Registers C: ZEH 


E: Drive 


Returned Value: First 3 bvtes 


of curredt DMA 
buffer 


Registers A: Error nag 


H: Physical Error 


The Get Disk Free Spacc function determines the number of fm sectors, 128 byte 
records, on the specified drive. Ihe calling program passes the drive number in 
regster E, with 0 for drive A, 1 for B, and so on, through 15 for drive P in a full 16- 
drive system. Function 46 returns a binary number m the first 3 b p s of the current 
DMA buffer. ?his number is returned in the following format: 


Disk F m Spacc Fild Formar 


k0 = low 
byte 


61 = middle byte 
fs2 = high 
byte 


Note that the returned free space value might be inaccurate if the drive has been 
marked Read-Only. 
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Upon rmm, rcgnrter A Is ut to zero nf the funcoon rs successful HOWWFI, 
tf the - 


BDOS Error Mode s one of the return rnadcr .uc Funcnon 45 ,and a phys~cal error 
s mcountcred, regtrtcr A Br u t ro OttM, 
255 drornal. and repsrcr H IS set to one of 
the following values: 


01 -Disk UO error 
04 - Invalid drive ermr 
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Redsten C: ZFH 


E: Chain Flag 


The Chain To Program function provides a means of chaining kom one program 
to the n u t without operator intervention. The calling program must place a com- 
mand line terminated by a null byte, OOH, in the default DMA buffer. If register E IS 
set to OFFH, the CCP inltialires the default drive and user number m the current 
program values when it passes control to the specified transient program. Otherwise, 
thew parameten arc set to the default CCP values. Note that Function 108, GedSet 
Program Return Code, can be used to pass a two byte value to the chained program. 


Function 47 does not mrn any values to the calling p r o w and any cnmun- 


tered crron are handled by the CCP. 


Registen C: 30H 
E: Purge Flag 


Returned Value: 


Rcgsters A: Error Flag 
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- 
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The Flush Buffers function forces the write of any write-pending records contained 
in lntcrnal blockmg/deblocking buffers. If register E is set to OFFH, thts function also 
purges all active data buffers. Programs that provide wrlte wlth read verify support 
need to purge tnternal buffen to ensure that verifying reads amally access the disk 
instead of returning data that is resident ~n internal data buffers. The CP/M 3 PIP 
utility is an example of such a program. 


Upon return, regster A IS set to zero nf the flush operation is successful. If a 


physical error is encountered, the Flush Buffers function performs different actions 
depending on the BDOS error mode (see Function 45). If the BDOS error mode is in 
the default mode, a message identifying the error IS displayed at the console and the 
calling program is terminated. Othemlw, the Flush Buffers functron reNrns to the 
calling program with register A set to OFFH and register H set to the following 
phystcal error code: 


01 : Disk UO error 
02 : Readionly disk 
04 : Invalid drive error 
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BDOS FUNCTION 49: GET 1 SET SYSTEM 
CONTROL BLOCK 


Entry Parameters: 
Registers C: 31H 
DE: SCB PB Addrcs 


Returned Value: 
Registers A: Returned Byte 
HL: Returned Word 


Function 49 allows access to parameters located in the CP/M 3 System Control 
Block [SCB). The SCB is a 100-byte data structure residing wlthin the BDOS that 
contains flags and data used by the BDOS, CCP and other system components. Note 
that Function 49 is a CP/M 3 specific function. Programs intended for both MPIM I1 
and CP/M 3 should either avoid the use of this function or isolate calls to this 
function m CP/M 3 vcrsion-dependent rcmom. 


To use Function 49, the calling program parser the address of a data structure 
called the SCB parameter block in register pair DE. This data smmm identifies the 
byte or word of the SCB to be updated or mnuned. The SCB parameter block is 
defined as: 


SCBPB: 
DB OFFSET 
i O f f s e t w i t h i n SCB 


DB SET 
i OFFH i f s e t t i n g a b r t e 
i OFEH i f s e t t i n g a w o r d 


I 
OOlH - OFDH a r e r e s e r v e d 


i OOOH i f a S e t o p e r a t i o n 


DW VALUE 
i B r t e o r w o r d v a l u e t o b e s e t 


The OFFSET paramew identifies the offset of the field within the SCB to be updated 
or accessed. The SET parameter determines whether Funnion 49 rs m set a byte or 
word value m the SCB or if it is to return a byte from the SCB. The VALUE 
parameter ir used only in set calls. In addition, only the first byte of VALUE is 
referenced in set byte calls. 
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UK caution when you r e SCB fields. Some of these parameters reflect the current 
state of the operating system. If they am set to invalid values, software errors can - 


result. In g c m l , do not use Function 49 to set a system parameter ~f another BDOS 
hnctlon can lrh~rrc the same result. For cxamplc, tunmon 49 can be called to 
update the Currcnt DMA Addrcsr field wnthln the SCB. This Is nor cqu~valenr to - 


maknne a Functson 26. S a D I M Addrcrr call. and undar~ne. the SCB Currcnt DMA 
. 
. 
- 
field in this way would result in system errors. However, you can u s ~ 
Function 49 to 
return the Curmt DMA address. The System Control Block is summarized in the - 
following table. Each of these fields is documented ~n detail in Appendix A. 


Reserved For System Use 
BDOS version number 
user nags 
Reserved For Systcm Use 
Program Error return code 
Reserved Far System Use 
Console Width (columnsJ 
Console Column Position 
Console Page Length 
Reserved For System Use 
CONIN 
Redirection flag 


CONOW Redirection flag 
AUXIN 
Redirection flag 


AUXOW Redirection flag 
LSTOW 
Redirection flag 
Page Mode 
Reserved For Systcm Use 
CTRL-H Active 
Rubout Active 
Reserved For System Use 
Console Mode 
Reserved For System Use 
Output Delimiter 
List Output Flag 
Reserved For System Uss 
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Table 34. ieontinuedl 


Offset 
Dercripnon 


3C - 
3D 
Current DMA Address 


I 3E 
Current Disk 
3F - 
43 
Reserved For System Use 
' 44 
Current User Number 


1 45 - 
49 
Reserved For System Use 
4A 
BDOS Multi-Sector Count 
4B 
BDOS Error Mode 


I 4C - 4F 
Drive Search Chain (DISKS A:,E:,F:) 


50 
Temporary File Drtve 


5 1 
Error Disk 
52 - 
56 
Reserved For System Use 
57 
BDOS flags 
58 - 
5C 
Date Stamp 


5D - 5E 
Common Memory Base Address 


SF - 63 
Reserved For Svstem Use 


If Function 49 is called with the OFFSET parameter of the SCB parameter block 
greater than 63H, the function performs no actlon but m r n s with registers A and 
HL set to zero. 
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BDOS FUNCTION SO: 
DIRECT BIOS CALLS 


Entry Parameters: 


Regirten C: 32H 
DE: BIOS PB Address 


I 
Returned Value: BlOS RETURN 
I 


Funaion 50 provider a direct BlOS call through the BDOS to the BIOS. The 
calling program passes the address of a data structure called the BIOS Parameter 
Block (BIOSPB) in regster pair DE. The BIOSPB contains the BlOS function number 
and register contents as shown below: 


BIOSPB: 
db FUNC 
i B I D S t u n e t i o n no. 


db AREG 
i A r e g i r t e l c o n t e n t s 


du BCREG 
i BC r e s i s t e r c ~ n t e n t s 


du DEREG 
i DE P e l i ~ t e r o o n t e n t r 


dw HLREG 
i HL r e g i s t e r c o n t e n t s 


System Reset (Function 0) is equivalent to Funaion 50 with a BlOS function 
number of 1. 


Note that the register pair BIOSPB fields (BCREG, DEREG, HLREGI are defined 
in low byre, high bye order. For example, in the BCREG field, the lint byte contains 
the C register value, the second byte contains the B register value. 


Under CP/M 3, direct BlOS calls via the BlOS jump vector arc only supported for 
the BlOS Console U0 and List functions. You must use Function 50 to call any other 
BlOS functions. In addition, Funaion 50 intercepts BIOS Functlon 27 (Select Mem- 
ory) calls and returns with register A set to zero. Refer to the CP/M Plus (CP/M 
Version 3) Operating System System Guide for the definition of the BIOS functions 
and their regster passing and return conventions. 
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BDOS FUNCTION 59: LOAD OVERLAY 


Entry Parameter% 


Registers C: 3BH 
DE: FCB Addmss 


Rrmrned Value: 
Registers A: Error Code 
H: Physical Error 


Only transient programs with an RSX header can use the Load Overlay function 
because BDOS Function 59 is supported by the LOADER module. The calling pro- 
gram must have a header to force the LOADER w reman res~dcnt after the program 
is loaded (see Section 1.3). 


Function 59 loads either an absolute or relocatable module. Relocatable modules 
are identified by a filetype of PRL. Function 59 docs not call the loaded module. 


The referenced FCB must be su-ssfully 
o p e d before Function 59 is called. The 
load address e specified in the first two random record bytes of the FCB, rO and rl. 
The LOADER returns an error ~f the load address is less than IOOH, or !I performing 
the requested load operation would overlay the LOADER, or any other Resrdcnt 
System Extensions that have been previously loaded. 


Wlen l o a d q relocatable files, the LOADER requires enough room at the load ad- 
dress for the complete PRL file including the header and ba map (see Append~x B). 
Otherwise an error is returned. Function 59 also returns an error on PRL file load 
requests if the specified load address s not on a page boundary. 


Upon return, Function 59 sets register A to zero if the load operation is successful. 


If the LOADER RSX is not resident m memory because the callrng program did not 
have a RSX header, rhe BDOS returns with register A set to OFFH and rcglster H set 
to zero. If the LOADER detects an invalid load address, or if rnsufhclent memory a 
available to load the overlay, Function 59 returns with register A set to OFEH. All 
other error returns arc consistent with the error codes returned by BDOS Function 
20, Read Scquent~al. 
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BDOS FUNCTION 60: CALL RESIDENT SYSTEM 
EXTENSION 


Entry Parameters: 


Registers C: 3CH 
DE: RSX PB Address 


Returned Value: 


Registen A: Error Code 
H: Physical Error 


Function 60 IS a spcdal BDOS function that you use when you call Resident 
System Extensions. The RSX subfunmon Is specified in a structure called the RSX 
Parameter Block, defined as follows: 


RSXPB: 
db FUNC 
i RSX F u n c t i o n n u m b e r 
db NUMPIRNS 
i Number o f w o r d p a r a m e t e r s 


d u PARMETER1 i P a r a m e t e r 1 
du PARMETERS i P a r a n r t e r 2 


. 
a 
. 


dw PIRMETERn i P a r a m e t e r n 


RSX modules filter all BDOS calls and capture RSX function calls that they can 


handle. If there is no RSX module present m memory that can handle a specific RSX 
function call, the call is nor trapped, and the BDOS rerums OFFH in registers A and 
L. RSX function numbers from 0 to 127 are avatlablc for CP/M 3 compatible soh- 
ware ux. RSX function numbers 128 to 255 are reserved for svrtem use. 
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Entry Parameten: 


Register C: 62H 


Rrmrned Value: 
Registers A: Error Flag 
H: Physical Error 


The Free Bloclts function scans all the currently logged-in drives, and far each 


drive r a m s to free space all temporarily-allocated data blocks. A umporarily-allo- 
cated data block is a block that has been allocated to a file by a BDOS write 
operation but has not been permanently recorded in the directory by a BDOS dose 
operation. The CCP calls Function 98 when rt receives control following a system 
warm start. Be sure to close your file, particularly any file you have written to, prior 
to calling Fundon 98. 


In the nonbanked version of CP/M 3, Fundon 98 frees only temporarily allocated 
blocks for systems that request double allocation vectors in GENCPM. 


Upon reNrn, register A is set to zro if Function 98 is sueccsshl. If a physical 


error is encountered, the F m Blocks function performs different actions dependrng 
on the BDOS error mode (see Function 451. If the BDOS ermr mo& is in the default 
mode, a message identifying the error rs displayed at the console and the calling 
program is termmated. Otherwise, the Free Blocks function returns to the calling 
program with register A set to OFFH and regster H set to the following physical 
error code: 


04 : Invalid drive ermr 
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1 
BDOS FUNCTION 99: TRUNCATE FILE 
1 


Entry Parameters: 


Reglrters C: 63H 
DE: FCB Address 


Returned Value: 


Regirterr A: Directory Code 
H: Extended or Physical Error 


The Truncate File function sea the last record of a file to the random record 
number contained in the referenced FCB. The calling program passes the address of 
the FCB in register pair DE, with byte 0 of the FCB specifying the drive, bytes 1 
through 11 specifying the filename and filetype, and bytes 33 through 35, 10, 
rl, and 


r2, specifying the last record number of the file. The last record number is a 24 bit 
value, stored wrth the least significant byte first, rO, the middle byte next, rl, and the 
hlgh byte last, r2. This value can range fmm 0 to 262,143, which corresponds to a 
maximum value of 3 in byte r2. 


If the file rpcc,hed hy the rrfrrcnccd FCB Is parsword protcclcd, the rorrcrt pmr- 


word must be plaad ~n thc first c~pht bytes of the current DhlA buffer, or have hern - 


prermously rsrahl~lhcd ar rhc default p~sswurd rcc Function 106 . 


Funcr~on 99 requires that the file spe~thrd hy the tCB no( he open, partlsulnrly t f - 


rhr lilr ha- hrcn wrlnrn to. In addtrnon, any autvrtcd FCB, namlng rhc file are nor 
valid ahcr Funcijon 99 I. called Clorc your file hrforc callong Funrrlon 99, and rhrn 
reopen it aher the call to continue processing on the file. 
- 
- 
- 
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Function 99 also requires that the random record number field of the referenced 
FCB specify a value less than the current file six. In add~tion, if the file IS sparse, the 
random record field must specify a record in a region of the file where data exists. 


Upon return, the Truncate function returns a Directory Code in register A with the 
value 0 if the Truncate function 1s successful, or OFFH, 255 decimal, 11 the file is not 
found or the record number is invalid. Register H Is set to zem in both of these 
cases. If a physical or extended ermr s encountered, the Truncate function performs 
different actions depending on the BDOS error mode (see Fundon 45). If the BDOS 
error mode IS m the default mode, a message ldcntifying the error is displayed at the 
conrole and the program a terminated. Otherwise, the Truncate function returns to 
the calling program with register A set to OFFH and rewster H x t to one of the 
following physical or extended error codes: 


01 : Disk VO error 
02 : Read-Only disk 
03 : Read-Only file 
04 : Invalid drive crror 
07 : Fllc password crror 
09 : ? in filename or filetype field 
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Registers C: 64H 
DE: FCB Address 


Returned Value: 


Registcn A: Directory Code 


The Sct Directory Label function creates a directory label, or updates the existing 


directory label for the specified dnve. The call~ng program passes in register pair DE 
the address of an FCB containing the name, type, and extent fields to be assxgned to 
the directory label. The name and type fields of the referenced FCB are not used to 
locate the d~rcctory label in the directory; they are simply copied into the updated or 
created directory label. The extent field of the FCB, byte 12, contains the user's 
specification of the directory label data byte. The definition of the d~rcctory label 
data byte is: 


bit 7 - Requlrc passwords for password-protected files 
(Not supported in nonbanked CP/M 3 systems) 
6 - Perform access dare and t~me stamoine 
. .. 


I . Pcrform update date and rlmr rramptng 
4 - Perform crcarc dare and ttmc rramplng 
0 - A111gn a new pasword to the dtm;tory labcl 


If the current directory label is password protected, the mrrea password must be 
placed in the first aght bytes of the current DMA, or have been previously estab- 
llshcd as the default password (see Function 106). If bit 0, the low-order bit, of byte 
12 of the FCB is set to 1, it indicates that a new password for the directory label has 
been placed m the second eight bytes of the current DMA. 


Note that Function 100 1s implemented as an RSX, DIRLBLXSX, in nonbanked 


CP/M 3 systnns. If Function 100 a called in nonbanked systems when the DIRLBL.RSX 
is not resident, an error code of OFFH is returned. 
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Function 100 also requires that the referenced directory contain SFCBs to activate 
date and timc stamping on the drive. If an attempt is made to activate date and timc 
stamping when no SFCBs exist, Function 100 returns an error code of OFFH in 
register A and performs no action. The CP/M 3 INITDlR utility lnitialiser a d~rcctory 
- 
for date and tlmc stamping by placing an SFCB record in every fourth entry of the 
directory. 


Funcrion 100 returns a Directory Code in register A with the value 0 if the direc- 
tory label create or update is successhtl, or OFFH, 255 dectmal, 11 no space exwe in 
the referenced directory to create a directory label, or if date and time stamping was 
requested and the referenced directory did not contam SFCBs. Register H rs set to 
zero m both of these cases. If a physical error or extended error 1s encountered, 
Function 100 performs different actions depending on the BDOS error mode (see 
Functlon 45). If the BDOS error mode rs the default mode, a message ldcntifying the 
error is displayed at the console and the calling program is terminated. Othemise, 
Function 100 returns to the calling program wlth register A set to OFFH and register 
H set to one of the following physical or extended error codes: 


01 : Disk UO error 
02 : Read-Only disk 
04 : Invalid drive error 
07 : File password error 
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BDOS FUNCllON 101: RETLIRN DIRECTORY 
LABEL DATA 


Entry Parameters: 
Registers C: 65H 
E: Drive 


Returned Value: 


Regrsten 
A: Directory Label 


Data Byte 
H: Physical Error 


The Return Dzrcctory Label Data function returns the data byte of the directory 
label for the specified drive. The calhng program passes the drive number m rcglstcr 
E with 0 for drwe A, 1 for drnvc 8, and so on through 15 for drwc P in a full sixteen 
drive system. The format of the directory label data byte is shown below: 


bit 7 - Require passwords for password protected files 
6 - Perform access dare and time stamping 
5 - Perform update date and ttmc stamplng 
4 - Perform create date and time stamping 
0 - Directory label exists on drwc 


Fundon 101 returns the directow lahel data bvte to the calline omeram in rceistcr 
" X - 
- 


A Regrster A equal to zero lndtcates that no dtrcctory label exlrts on the spec~ficd 
dnve If a phystcal error rs encountered by Function 101 when the BDOS Error mode 
e m one of the return modes (see Function 45), this funct~on rerurns with register A 
set m OFM, 255 decimal, and regrsrcr H set to one of the following: 


01 : Disk VO error 
04 : Invalid drwe error 
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I 


BDOS FUNCTION 102: READ FILE DATE STAMPS 
AND PASSWORD MODE 
I 


Entry Parameters: 


Reglsterr C: 66H 
DE: FCB Address 


Returned Value: 
Registers A: Directory Code 


H: Physical Error 


Funct~on 102 returns the date and time stamp information and password mode for 


the specified file ~n bytc 12 and bytes 24 through 32 of the specified FCB. The callmg 
program passes in register parr DE, the address of an FCB in which the drive, file- 
name, and filetype fields have been defined. 


If Function 102 s successful, it sets the following fields in the referenced FCB: 


bytc 12 : Password mode field 


ba 7 - Read mode 
bit 6 - Wrtte mode 
bit 4 - Dcletc mode 


Byte 12 equal to zero indicates the file has not been assigned a password. In non- 
banked systems, byte 12 is always set to zero. 


bytc 24 - 27 : Create or Access time stamp field 
byre 28 - 31 : Update time stamp field 


lbe date stamp fields are set to binary zeros rf a stamp has not been made. The 
format of the time stamp fields is the same as the format of the dare and tlmc 
structure described in Functnon 104. 
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Upon return, Function 102 returns a D~rcctary Code in register A with the value 


zero if the function ts successful, or OFFH, 255 decimal, if the specified file IS not - 


found. Register H is set to zero m both of these caxs. If a physical or extended error 
is encountered, Function 102 performs d~fierenr actions depending on the BDOS 
crror mode (see Function 45). If the BDOS cnor mode IS in the default mode, a - 
message jdenrifying the error is displayed at rhe console and the calling program rr 
termmared. Othenvire, Function 102 returns to the calling program wlth register A 
set to OFFH and register H set to one of the following physical or utcnded crror - 
codes: 


01 : Dirk VO crror 
04 : lnvalzd drive error 
09 : ? in filename or filetype field 
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Entry Parameters: 
Registers C: 67H 
DE: FCB Address 


- 


Returned Value: 
Registers A: Dlrcctory Code 
H: Physical Error 


BDOS FUNCIlON 103: WRITE FILE XFCB 


The Write File XFCB function creates a new XFCB or updates the exlsti.g 
XFCB 
for the spec~ficd file. The calling program passes in regrrter parr DE the address of an 
PCB in which the drive, name, type, and extent fields have been defined. The extent 
field spcc~fics the password mode and whether a new password is to be assigned to 
the file. Ihe format of the extent byte is shown below: 


FCB byte 12 (ex) : XFCB password mode 
ba 7 - Read mode 
bit 6 -Write mode 
bit 5 - Delete mode 
bit 0 - Assign new password to the file 


If the specified file is currently password protected, the correct password must reside 
in the first erghr bytes of the current DMA, or have been prcviourly established as 
the default password (see Function 106). If bit 0 is set to 1, the new password must 
reside ~n the second eight bytes of the current DMA 
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Upon return, Function 103 returns a Directory Code m register A with the value 


zero if the XFCB create or update is successful, or OFFH, 255 dectmal, II no directory 
label exlsa on the specified drive, or the file named in the FCB is not found, or no 
space exists in the dtrcctory to create an XFCB. Fundon 103 also returns wlth OFFH 
in register A nf passwords are nor enabled by the referenced directory's label. On 
nonbanked systems, thls function always returns with register A = OFFH because 
passwords arc not supported. Register H 8s set to zero m all of there caxs. If a 
physical or extended error is encountered, Function 103 performs different actions 
depend~ng on the BDOS error mode (see Function 45). If the BDOS error mode is 
the default mode, a message identifying the error is displayed at the console and the 
calling program is terminated. Othenulsc, Fundon 103 returns to the calling pro- 
gram with register A set to OFFH and register H set to one of the following physlcal 
or extended error codes: 


01 : Dirk UO error 
02 : Read-Only disk 
04 : Invalid drive error 
07 : File password error 
09 : ? in filename or filetype field 
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Entry Parameters: 
Registers C: 68H 
DE: DAT Address 


Rcturncd Value none 


The Set Datc and Time function sen the system internal date and time. The calling 


pmgram passes the address of a Cbyu structure containing the date and time speci- 
fication in the register pair DE. The format of the date and time (DAT) data structure 


1s: 


bye 0 - 1 : Datc field 
byte 2 
: Hour field 
byte 3 
: Minute field 


The date is represented as a 16-bit integer with day 1 corresponding to January 1, 
1978. The time IS represented as two bytes: hours and minutes are stored as two 
BCD digits. 


This function also wts the seconds field of the system date and time to z r o 
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Registers C: 69H 
DE: DAT Address 


Returned Value: 


Rcgtsrcr A: seconds 


The Get Date and T m c function obta~ns the system internal datc and time. The 


calhng program passes in register pair DE, the address of a 4-byte data structure 
which receives the date and rlmc values. The format of the datc and time, DAT, data 
strumre 1s the same as the format dcrcrlbed in Funcuon 104. Function 105 also 
returns the seconds field of the system date and time in register A as a ouo digit BCD 
value. 
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Entry Parameters: 


Regsters C: 6AH 
DE: Password Address 


Rcmrned Value: none 


Ihe Set Default Password function allows a program to specify a password value 
before a file protected by the password 1s accessed. When the file system accesses a 
password-protected file, it checks the current DMA, and the default password for the 
correct value. If either value matches the file's password, full access to the file is 
allowed. Note that this function performs no action in nonbankcd CP/M 3 systems 
because file passwords are not supported. 


To make a Functton 106 call, the calling program sets register pair DE to the 
address of an 8-byte field contarrung the password. 
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Registers C: 6BH 
DE: Scrlal Number Field 


Returned Value: Serial number fidd wt 


Function 107 returns the CP/M 3 serial number to the 6-byte fidd addressed by 


regster pair DE. 
- 
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BDOS FUNCTION 108: GETISET PROGRAM RETURN 
CODE 


Entry Paramcfers: 


Registers C: 6CH 


DE: OFFFFH (Get) or 
I 
Program Return Code (Set) 


Returned Value: 
Register HL: Program Return Code or (no value) 


CP/M 3 allows programs to sn a return code before terminating. This provides a 


mcchantsm for programs to pass an error code or value to a following job step in 
batch environments. For example, Pmgram Return Codes are used by the CCP in 
CP/M 3's mndxtional command line batch facility. Conditional mmmand lines are 
command lines that begin with a colon, :. The execution of a conditional command 
depends on the successful execution of the preccdtng command. The CCP tests the 
return code of a terminating program to determine whether it successfully completed 
or tcrrmnated in error. Program return codes can also be used by programs to pass 
an error code or value to a chained program (see Function 47, Chain To Program). 


A program can set or ~nferrogate the Program Return Code by calllng Function 


108. If regLjtet pair DE = OFFFFH, then the cumnt Program R a m Code is returned 
in register parr HL. Othcmac, Function 108 sets the Program Return Code to the 
value contained in register pair DE. Program Return Coder arc defined in Table 3-5. 
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I 0°00 


We CCP ln~aaltur he Pmgram Rmm Code to zcm udns - 
rhc program 1s loaded as the result of program cham. 


Table 3-5. hogrnm Return Codes 
- 


Codc 
Meaning 


FFSO - 
FFFC 
Rcscrvcd 


FFFD 
The program is terminated because of a fatal BDOS error. 


FFFE 
The program is termmated by the BDOS because the user 
typed a CTRL-C. 


- 
- 


0000 - 
FEFF 
Successful return 
- 
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- 
- 


Registers C: 6DH 
DE: OFFFFH (Get) or Console Mode (Set) 


Returned Value: 


Register HL: Console Made or (no value) 


- 
A program can rcr or Interrogate the Lonrolc Mode by eallnng tunnmon 109 If 


regrtcr paw DE = OFFFFH, rhcn the current Conrole .\(ode 8s rcrurncd ~n rrplrtcr 
HL Orhcrwlsr, Funawn 109 rrlr rhc Conwlc hlodc to the value cunra~ncd ~n reg,<- 
ter palr DE. 


The Console Mode is a 16-bit system parameter that determines the action of 
certain BDOS Console 110 functions. The definition of the Console Mode is: 


bit 0 = 1 - CTRL-C only status for Function 11. 
= 0 -Normal status for Function 11. 


bit 1 = 1 -Disable stop scroll, CTRL-S, start scroll, CTRL-Q, support. 
= 0 -Enable stop scroll, start scroll support. 


bit 2 = 1 -Raw console ourput mode. Dirablcr tab upanston for Funct~ons 2, 
9 and 111. Also disables printer echo, CTRL-P, support. 
= 0 -Normal console output mode. 


blr 3 = 1 - Dlsablc CTRL-C program termination 


= 0 -Enable CTRL-C program termination 
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bits 8,9 
-Conrole status mode for RSXs that perform console input redirec- 
tion from a file. These brts determine how the RSX responds to 
console status requests. 


bit 8 = 0, bit 9 = 0 - conditional status 
ba 8 = 0, bit 9 = 1 - false status 
bit 8 = 1, bit 9 = 0 -true Status 
ba 8 = 1, bit 9 = 1 -bypass redirection 


Note that the Console Mode bin arc numbered from right to left. 


The CCP initializes the Console Mode to zero when it loads a program unless the 


progam has an RSX that overrldcs the default value. Refer to Section 2.2.1 for 
detailed information on Console Mode. 
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Entry Parameters: 
Registers C: 6EH 
DE: OFFFFH (Get) or 
E: Output Delimiter (Set) 


- 


Returned Value: 
Register A: Output Delimiter or (no value) 


BDOS FUNCTION 110: GETISET OUTPUT DELIMITER 


- 


A program can set or interrogate the current Output Delimiter by calling Function 
110. If reester pair DE = OFFFFH, then the current Output Delimiter is murned m 
- 
register A. Otherwise, Function 110 sets the Output Delimiter to the value contained 
in register E. 


Function 110 sen the string delimiter for Funnion 9, Print String. The default 
- 
dellmiter value is a dollar s~gn, $. The CCP restores the Output Dellmiter to the 
' 
default value whm a transient program s loaded. 
- 


- 
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I 
BDOS FUNCTION 111: PRINT BLOCK 
I 


Entry Parameters: 


Registers C: 6FH 
DE: CCB Address 


Returned Value: none 


The Print Block function sends the character string located by the Character Con- 
trol Block, CCB, addressed in register pair DE, to the logical console, CONOUT:. If 
the Console Mode a in the default state (see Section 2.2.1), Function 111 expands 
tab characters, CTRL-I, xn columns of eight characters. It also checks for stop scroll, 
CTRL-S, start scroll, CTRL-Q, and echoes to the logical list dcvlce, LST:, if printer 
echo, CTRL-P, has been invoked. 


The CCB format ir: 


byte 0 - 1 : Address of character string (word value) 
byte 2 - 3 : Length of character string (word value) 
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- 


Entry Parameters: 
Registers C: 70H 
DE: CCB Address 


Returned Value: none 


The List Block function sends the character string located by the Character Control 
- 
Block, CCB, addmscd in register pair DE, to the logical list device, LST:. 


The CCB format is: 
- 


byte 0 - 1 : Address of character string (word value) 
byte 2 - 3 : Length of character string (word value) 


3 BDOS Calls: Function 152 
CP/M 3 Programmcr'r Guide - 


Registers C: 98H 
DE: PFCB Address 


Rrmmed Value: 


Rcglster HL: Rrmm c d c 


- 


The Parse Filename function parses an ASCII file specification and prepares a File 


Control Block, FCB. The calling program passes the address of a data srmcture called 
the Parse Filename Connol Block, PFCB, in register pair DE. The PFCB contains the - 
address of the input ASCII filename string followed by the address of the target FCB 
as shown bdow: 


PFCB: OW INPUT 
i A d d r e s s o f i n r u t O S C I I s t r i n g 


DW FCB 
i addle^^ 0 7 t a r g e t FCB 


The maxlmum length of the input ASCII string to be paned is 128 byes. The target - 
FCB must be 36 bytes in Imgth. 


Funnlon 152 assumes the input string contains file specifications m the following - 


form: 


where items enclosed in curly brackets are optional. Function 152 also accepts iso- 
lated drwe specifications d: in the input string. When st enmunterr one, it xts the 
filename, filetype, and password fields m the FCB m blank. 
- 


- 


B DIGITAL RESEARCHm 


3-96 
- 


- 


CP/M 3 Programmer's Guidc 
3 BDOS Calls: Function 152 


- 
The Parse Filename function parses the first file specification it finds in the mput 


string. The b d o n first elimnatn leading bla& and tabs. The lnrdon then assume 
that the file spec~fication ends on the first delimiter a encounters that is out of 
- 
context with the specific ficld it is parsing. For instance, if it finds a colon, and it is 
not the second character of the file specification, the mlon delimits the entire file 
spec~fication. 
- 
Function 152 recognizes the following characten as delimiters: 


space 
- 
tab 
return 
null 
- 
; (semrcolon) - except before password field 
= (equal) 
< (less than) 
> (greater than) 
- 
. (period) - wcept after filename and before filetype 
: (colon) -except before filename and after drive 
, (comma) 
- 
1 (vertical bar) 
[ (left square brakn) 
I (right square bracket) 
- 
If tuncnon IS2 encounters a nongrsph~c character ~n rhc range 1 through 31 not 
lhrrcd above. n m a r . rhc chrractcr a9 an crror fie Pane Fnlcnamc functron ~nnt~al~lrr 
the ,perled FCR shown ~n Table 3 6. 


- 
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Table 3-6. FCB Format 
- 


I 
outi ion 
I 
Contents 
I 


byte 0 


byte 1-8 


byte 9-11 


byte 12-15 


byte 16-23 


byte 24-31 


The drive ficld is set to the specified drive. If the drive is not 
specified, the default drive code la used. 0 = default, 1 = A, I 


The name is set to the specified filename. All Icners are con- 
vened to upper-case. If the name is not clght characters long, 
the remaining byns in rhe filename ficld are padded wth blanks. 
If the filename has an asterisk, ', all remaining bytes m the 
filename field are filled ~n with question marks, ?. An error 
occurs if the filename is more than eight bytes long. 


The type is set to the specified filetype. If no filerype is spec!- 
ficd, the type field is initialized to blanks. All letters are con- 
vened to upper-case. If the type is not three characters long, 
the remaining bytes in the f i l q e field are padded with blanks. 
If an asterisk, ', occurs, all remaining bytes arc filled in with 
question marks, ?. An error occurs if the type fidd is mom 
than three bytes long. 


Filled in wxth zeros. 


The password field is set to the specified password. If no pass- 
word is specified, it is initialized to blanks. If the password is 
less than eight characters long, remaining byte are padded 
with blanks. All letters are convened to upper-case. If the pass- 
word field is more than eight bytes long, an error occurs. Note 
that a blank in the first position of the password field implies 
no password was specified. 


~eserved for swtem uw. 
I 


- 
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If an error occurs, Function 152 returns an OFFFFH in register pair HL. 


On a succepsful parse, the Parse Filename fumeon checks the next item in the 
input string. It skips over trailtng blanks and tabs and looks at the n u t character. If 
the character is a null or carriage return, it m r n r a 0 indicating the end of the input 
string. If the character is a dellmiter, it returns the address of the delim~tcr. If the 
character is not a del~mter, it returns the address of the first trailing blank or tab. 


If the first non-blank or non-tab character in the input string is a null, 0, or 
carriage m r n , the Parse Rlcnamc function returns a zero indtcating the end of 
string. 


If the Parse Filename function is to be used to parse a subsequent file specification 
in the input string, the returned address must be advanced over the delimktcr before 
placing a in the PFCB. 


End of Section 3 


- 
Section 4 
Programming Examples 


T h c program? presented ~n thnr sealon lllustrarc how to use the RDOS hmct~ons 


dcrcr~bcd ~n rhc prrvrour xmun The cxamplcr show how to copy a filc, how to 
- 
dump a file, how to create or access a random amrr filc, and how to wrlrr an RSX 
program. 


4.1 A Sample File-To-File Copy hogram 


The following program illusnates simple file operations. You can mate the pro- 
gram source file, COPY.ASM, using ED or another edimr, and thm assemble 
COPY.ASM using MACR. MAC produces the file COPY.HEX. Use the utiliry 
HEXCOM to produce a COPY.COM file that can u-tc 
under CP/M 3. 


The COPY program fint sets the stack pointer m a local area, then moves the 
second name from the default area at 006CH to a 33-byte file control block named 
DFCB. The DFCB is then prepared for file operations by clearing the curmt record 
field. &cause the CCP sets up the source FCB at OOSCH upon entry to the COPY 
program, the source and destinataon FCBs are now ready for pmcessing. To prepare 
the source FCB, the CCP places the first name into the default FCB, with the proper 
fields zcrocd, including the current m r d field at 007CH. 


COPY continues by opening the source file, deleting any w~sting destination file, 
and then creating the desunation file. If each of these operations is successful, the 
COPY program loops at the label COPY until each record is read from the source 
file and placed into the destination file. Upon completion of the data transfer, the 
desttnation file is closed, and the program murns to the CCP command level by 
jumping to BOOT. 
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i 
,.#.I. 
tll.-,o-tfl. 
C O P " .ro*r.m 
I 
I 
a t th. 
CC. I.".l, Ih. 
romm.nd 


I , 
I 


0000 = 
b o o 1 


0005 . 
bdos 


005" = 
f c b l 


OO5I = 
S f l i b 


0060 = 
f c b 2 


OOQO . 
db"tf 


0100 . 
tr. 
I 


0009 a 
r r l n t f 


COP" .:x.r 
b:"." 


...,,I 
t h . 
t11. 
"...d 
X." 
tram d r l v l 


1 0 a 111. 
narnd u,u on d r l u e b t 


I." 
OOOOh 
I .".,*" 
,.bolt 


e-u 
OOO5h 
1 bd.5 
e n t r y r o l n t 


o05rh 
I f i r s t fz1. 
name 


eru 
f o b 1 
I sourlie t c b 


w u 
006ch 
i second f ~ l e 
name 


. 
. 
u 
OOBOh 
I d e f a u l t b u t f l r 


e.u 
OlOOh 
I b r # l n n l n l ef I r a 


I," 
9 
I rr,n, 
buff., 
tun". 
.." 
I 5 
I 0p.n 
f11* tunc. 


I," 
I B 
I "l... 
f,l. 
f""0. 


eru 
19 
I 61111s t l l * funr. 


..u 
20 
1 ,l.".n,,al 
read 


rru 
21 
I snruent1.l 
u r l t n 


.ru 
22 
I mak. 
f i l l tunr. 


D l , 
I.. 
I b.ll""l", 
*t I.. 
I", 
1.1.1.011 
1.c.1 
It..K 


I 
movr rscond t i 1 1 nan. 
t o drab 


0103 0.10 
.ul 
a o l Q 
I h a l f n n f c b 


0105 1 1 6 ~ 0 0 
1x1 
d,trbZ 
I sourli. 
a t aoul 


0109 2Ld.01 
1x1 
h t d f o b 
I d l l l l n a t l o n f o b 


OlOb1. 
mfobi 
I d a x 
d 
I soural f c b 


0100 I 3 
I n x 
d 
I read7 nmxt 


OlOd 77 
.." 1,. 
l d . . t f l b 


0101 23 
Inx 
h 
I r r a d v n e x t 


010f Od 
dr, 
o 
I r D u n l 1 G , , . O 


0110 c2ObOI 
Jnz 
mfcb 
I l o o * 1s t1M.S 
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0117 115000 
I x l 
dlsfcb 
I s o u , c l ill* 


0111 cd6901 
ma11 
oren 
l e r r o r lf 255 
- 
O l l d 11870L 
1XI 
denmt11.i 
read7 an$sa,e 


0120 3" 
1 n r . 
i 255 beco.er 
0 


0121 cc6101 
o r 
f x n ~ r i d ~ n e ~f no f111 


- 
i 
r o u r r ~ f,1I 
o r e n , .re. 
dert,na,,on 


0124 l i d 8 0 1 
1 x 8 
d t d l a b 
i d e r t l n a t l o n 


0127 cd73OI 
c a l l 
de1.t. 
i remove ~f 
P F @ S P ~ % 


- 


O l 2 r IldaOL 
IXL 
d3dl.b 
i d l l l l n l l l l n 


0126 rdB2OL 
caLL 
make 
; nrea\e th. ill. 


0130 119601 
1XI 
d e n o d l r i read7 n l l r l l l 


0133 30 
l n r 
a 
i 255 heconer 0 


0114 0 ~ 6 1 0 1 
0 2 
f ~ n l r i done $ f n o d l r %rare 
- 
r 
i 
r o u r c ~ 111. 
o r e n + d e l t f i l l a r m 


i 
COP" "",,I 
end 0 , f r l * Iln .ourre 


no, 
r n d o f 111.1 
ur1te t h e r r l o l d 


1°C 
d,df.b 
i d l l t l n . t l o n 
..,I 
YII,. 
i ~ I f t . l.0D.d 
I", 
d,5.ac, 
! read7 msss.'. 


O I . . 
i 0 0 l f Y l l t e . I 


cnr 
f l n l s 
I end lf $ 0 


Jnr 
O O P Y 
i IOOP 
until eof 


znr 
1 255 b e r ~ l e l 
00 


c r 
I ~ n l r i should n o t h a r r ~ n 


- 
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0173 0.13 
delete2 nu1 
ned.111~1 
- 


0175 ~ 3 0 5 0 0 
rnr 
bdor 


0182 0.16 
x a X C : 
m u r 
c>#nbnf 


OlBa ~ 3 0 5 0 0 
rnr 
b d a l 


i 
"ll"l0ll nPrla,*, 


Ole7 S e S f Z O l n o f L I ~ r db 
'no I s u r c e ?1IeS' 


0196 6e6120Snodlr: 
d b 
'no d l r . c t o r 7 
s ~ a c l l ' 


01.9 
6f757P1sPaOt: 
db 
' o u t of d a t a SPICPS' 


01bb 777269Jur~lll: db 
' u l l t l rrotlOted'S' 


0110 6361700norlal: db 
'c0.r 
conPlcteS' 


Note that thlr program maker several simplificarionr and could be enhanced. First, 


it does nor check for invalid filenames that could, for example, contam ambiguous - 


references. Th~s situation could be detected bv scannine the 32-byte default area 
srantng at locarlon OOJCH for ASCII 
marks. fo check that the filenames 
have, in fact, been mcluded, COPY could check locations OO5DH and 006DH for - 
nonblank ASCll characters. Finally, a check should be made to ensure that the source 
and destination filenames are difhrenr. Speed could be improved by buffering more 
data on each mad operation. For example, you could dctermlne the n u of memory 
by fetching FBASE from location 0006H, and use the entire remaining ponton of - 


memory for a data bufhr. You could also use CP/M 3's Multi-Sector UO facility to 
read and write data in up to 16K unm. 
- 
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- 
4.2 
A Sample Filc Dump Utility 


The following dump program mads an input file specified in the CCP command 
line, and then displays the content of each record in hexadecimal format at the 
- 
console. 


i DUMP .r.*r.. 
r e a d , 
."rut 
f l l . 
a n 4 dl,.l.". 
hex d a t a 


. 
2 
it*.= 
,unct,.n 


I." 
9 
i b U f f l l r r , n t e n t r * 


P 
~ 
U 
1 1 
I b r e a l IF* 
l u n o l l o n I I r u * 
I ) c h a r 


r r u 
1 5 
I f 1 1 1 arm 


e r u 
2 0 
I r e a d function 


u 
S c h 
I f l l P o o n t r o l b l o c k a d d r e s s 


1." 
@Oh 
r l n r u t d u l b u f f . , 
addre.5 


"0" 
I , r r h l r 
. h . r * c t * r r 


I." 
Odh 
i c a r r l l l l rFtum 


I." 
0.h 
ill". 9e.t 


d a d 
,r 


en,.* 
rt..l 
Pol",., 
1" h l f r o m t h e r c r 


l h l d 
DLd.. 


s e t 5. 
t o l o c a l ,%.CU 
I... 
1I.lt.l.d 
a t 1 L " l . l 


I", 
I . , l t k t l . 


- 
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: 
f L l P 
thnr., 
( x u 8 mrmr .~SS.(I 
and return 


0112 L l f 3 O l 
IxI 
deoPnM., 


0115 c d l c o l 
1.11 
r r r 


o i l 8 ~ 3 5 1 0 1 
J 
~ 
P 
finis 
i r o r.turn 


.... 
olza C ~ S Z D I 
-11 
~ n b 


0127 . I 
POP 
h 
IICC~II 
Lxnr rosltlon 


OL28 6a5101 
r c 
trna. 
8 c . r ~ ~ re* D Y tnb 17 end f11e 


OlZb 47 
#mu 
b t a 
I 
. l i n t 
hmx ua1u.r 


i 
chack f o r l ~ n e 
f o l d 


OLZc 76 
I O U 
a11 


OIZ~ .not 
."a 
0 t h 
i r h e r k 
IOW 
4 b ~ t s 


O l 2 f 121401 
dnz 
nonu. 


I 
v r r n l L l n l numb.? 


0132 rd72OI 
c a l l 
c r l f 
I 
I 
Ch,CK 
t o t bt..k 
R." 


Ol3S ~ 6 5 9 0 1 
0.11 
b r e a l 
I 
armurn 11) . 
1 1 f o h a r n c t l r read* 


OL38 Of 
,PC 
U n t o oarrv 


0139 6as101 
f l n l r 
160 n o t ~ r l n r 
an* * o r * 


I 0131 7c 
IOU 
8 1 h 


0136 IdBfOL 
1111 
P h l x 


0110 76 
no0 
a11 


01a1 rd8fO1 
0.11 
rh-x 


"onurn, 


01114 23 
inx 
h 
1,. 
nrxc Iln. 
nu*b#r 


OLlS 3120 
M V I 
a ? ' ' 


0147 166501 
* a l l 
r n h a r 


Olaa 78 
IOU 
a t b 


Ol4b l d U f O 1 
c a l l 
r h ~ x 


014e c323Ol 
J 
t l o l r 
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i 
- 
I,",.: 
i 
end 0 , d".. 


0 1 1 1 od720L 
m a l l 
r r l f 
- 0 1 5 4 Za150Z 
I h l d 
old.. 


0117 f 5 
s r b l 
I 
1I.11 
PD1.t.l 
00"t.l". 
.or'$ 
St..X 
I...,,." 


OLJB "9 
P e t 
i t 0 t h l 1c. 


irrim a o h a r a c t e r 
mush h ' r u s h d l r u s h b i r a u e d 
*"I 
O l t " . l l 


ma" 
,,a 


c a l l 
bdos 


POP b I P a r d l PO. 
h l I e l t l t . d 
,., 


*no 
r10 


1 . s ~ t h a n o r ~ ~ Y I I 
11 9 


ad. 
' 0 ' 


J.. 
.," 


,,.a,.. 
0, ..".I t o I 0 


i d 1 
' a ' - l 0 


rall 
.char 


I., 
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O l b l 3 7 
OlbZ 09 


Olb3 Sf 
O l b l 1600 
Olb9 3s 
01b7 321302 


Olba ZiB000 
Olbd 19 


Olb. 
7e 


i,.t 
n e x t b " t l 


ld. 
Xb. 


".I 
BOh 


rnr 
$0 


?Pad a n o t h r r b u f f e r 


c a l l 
d l s K v 


or. 
ir.ro 
u a l u l I T read 0 1 


r 2 
10 
;for 
l " 0 I h l l b*,. 


."d 
0, 
*.,a, 
,.rum 
w i t h I.,?" 
s e t t o r 101 


.,c 
r., 


;,.ad 
th. 
b",. 
a t buff+,., 
a 


nou 
r e . 
i l r b y t e o f b u f f e r Index 


."I 
d , 0 
Id."bL, 
r r ~ c l r l o n ind." 
t o d* 


in, . 
i,ndex=lndrx+l 


.,a 
ib. 
;bark l o l . l D I * 


PO,",.. 
1. 
.ncr...ntld 


3.". 
t h l .Ul,."t 
fI1. 
l d d l l l l 


L x r 
h e b u f f 


dad 
d 


a b r s l u t e o h a t a c t e r addrers 1% I n h l 


# O " 
a m 


b r t . 
1 % i n ,he 
accu*u1.tor 


0,. 
a 
,11111 1 1 l P " b l t 


, s t 
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<*,UP: 
i s * , 
UP ,I,- 
: 
orrn Ihr f i l e l o r lnrur 


O l r l a, 
"Pa . 
!I110 t o I C C Y I 


0112 3 2 7 1 0 0 
s t a 
l r b e r 
$ c l e a r current r e c o r d 


8 


O l e 5 1 1 5 0 0 0 
1 x 1 
d t l r b 


0,na OC01 
."I 
c,.r.nf 


010. 
a d 0 5 0 0 
1.11 
bdor 


1 
255 ~n arrun I , oren ~ r r ~ r 
- 
O l c d 09 
~ I I 


dank,: 
i r e a d d i s h f ~ l e 
t e c o r d 


030. c5d505 
rush h ! push d l push b 
- 
O l d 1 l l 5 1 0 0 
1 x 1 
d t i r b 


O l d l op1a 
."I 
r.rr.dr 


O l d 6 rdO5OO 
c a l l 
b d o r 


Old3 r l d l e , 
PO. 
b! PO. 
d l PO. 
h 
- 
O l d 0 19 
I*, 


- 
0 2 1 5 
o l d s r , 
d r 
2 
t e n t r y sr u a l u t l t o r c c r 
, 


- 
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A Sample Random Access Program 


Thts example is an extenswe but complete example of random access operation. 
The following program reads or writes random records upon command from the 
terminal. When the program has been created, assembled, and placed into a file 
labeled RANDOM.COM, the CCP level command 


can start the test program. In this case, the RANDOM program lwks for a file 
X.DAT and, if it finds it, prompts the console for input. If X.DAT is not found, 
RANDOM creates the file before displaying the prompt. Each prompt takes the 
form: 


next command? 


and 1s followed by operator input, terminated by a carriage return. The input com- 
mands take the form: 


where n 1s an integer value in the range 0 to 262143, and W, 
R, F, and Q are simple 
command characters corresponding to random write, W, random read, R, random 
wrlte wlth zero fill, F, and quit processing, Q. If you enter a W or F mmmand, the 
RANDOM program issues the prompt: 


t 
~ 
~ 
e 
d a t a : 


You then respond by typing up to 127 characters, followed by a carnage return. 
RANDOM then writes the character string rnto the X.DAT file at record n. If you 
enter an F command, the RANDOM program fills previously unallocated data blocks 
wlth zeros before writine record n. If vou enter the R command. RANDOM reads 
record number n and d~,play, the srnng value at the con,ole. If you cntcr rhc Q 
command, rhr X.DAT file IS closed, anJ the program returns ro the conrole com- 
mand processor In the Bntcrra of brcunry, the only crmr mcrsagr 1,. 


0 0 - 
- 0 - 
0 - - 
'no 0 
. ,, 
--. 
- 
--.-a,- 
-. * * * * * 
- - . 
..o 
* - 
* 


0 
* 
. 
* 
.. 
. 
% 
* 
* 
m 
. 
- . 
.- 
s. 
* 
.. ..* 
* 
= = * * 
7 . 
*-• 
- 
9 
. 
* 
- 
. 


- 
0 
. 
* 
= 
* 
0 0 - * 
. 
a - - * . . 
0 - - * " 
'no 7 . 
0 . 
7 - 
* 
. 
* 
.-• 
* 
. 
. 
* 
* 
-- -.. . 
- * 
- * 
7 . 
" * . 


0 . . 
m 
* 
- 
.... . * . * 
- 
. 
" 
* 
- 3 - * 
m . 
9 
- * 
. 
* - 
* - 
.. " * - . 
T 
m 
- * . 
- ". 
7 - . " . 
0 . . . ? 
- 
. . . 
= 
* 
= 
. 
.. . 


* 
G 
n 
. 
. 
* 
. . . 
. 
* 
. 
. . 
* 
. 
* . 
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.................................................... 


i s load 6Pt rat-ur f i l e f o r rando. 
a 0 c . r ~ 
.................................................... 
0100 313703 
1x1 
s ~ e s t a r l i 
, 
I 
v l r l l l n 3.1' 


0103 OEOC 
mu1 
c ~ u t r 3 l o n 


0105 C00500 
c a l l 
bdor 


OLOQ FEZ0 
0.1 
3 l h 
iu.rslon 
3 . 1 o r b r t t l l ' 


0100 DZ1601 
mc 
u e r l ~ l 


I 
bad u n r r l o n t #e%ra#l and $0 barl: 


0100 116102 
I x r 
dtbadu.r 


0110 C03102 
C a l l 
r r l n t 


0113 CJOOOO 
JIP 
reboot 


1 
u e r l o k i 
i 
. O l l l . t 
"IIII." 
( 0 1 ,."do* 
.ccrrr 


0116 OEOF 
mur 
rtor.nf 
i l r l n default I r b 


0116 3A5000 
rdname: 
Ida 
f c b r l 


- 
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- 
0146 CD3C02 
c a l l 
r.adcon 
i r r a d n l x l r o * n a n d 


O l l E 227000 
l h l d 
n n r e c 
i s t a r e l n r u t record. 


0151 217F00 
1x1 
h e r l n o u f 


015a 71 
# I V 
ner 
i r e t r a n r ~ c h l l h b r t r 


0155 FESl 
o r , 
'0' 
~ ~ U I I ? 


0157 C2B901 
rnr 
not. 


.................................................... 
- 
not.: 
i 
n o t t h e r u l l c o r n a n d . r a n d o m u r l t e ? 


01B9 FE57 
c r l 
' U ' 


0166 CZSCOI 
dnz 
not" 
- 
i 
i 
t h l s 1 3 
r a n d o m u r l t e . 1111 b u f f e r v n t l l r r 


016E 118302 
1x1 
d t d a 1 1 1 I 


0171 C03102 
1111 
P l r n t 
! d a t a rromrt 
- 
0174 0E7F 
nu, 
c t l Z 7 
l u r l o I 2 7 c h a r a r l l r l 


0175 218000 
IXL I t b u f f 
i d l l t l n a t i o n 


Ill*.: 
l,..d 
next .h,r.ct.r 
t o b u f f 


0179 C5 
push 
b 
; s a v e ~ o u n l l ? 
- 
0171 E5 
push 
h 
i n . * % d e r t x n a t l o n 


0176 COO802 
c a l l 
( ~ t c h l l c h a r a c l . l 
t o 


017E EL 
ror 
h 
ir1111r1 
coumer 


O I ~ F 
C I 
POP 
ir111.11 
n e x t t o r r l l 
- 
OlHO FEOO 
cP1 
c r 
i l n d o f line' 


01BZ CASllOI 
* r 
er1o.r 
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i 
" 0 % end, stor* rh.r.0l.r 


0185 77 
mou 
" f a 


0186 23 
1.1 
h 
I n s x t t o t i l l 


0187 OD 
dCI 
I 
il0Unl.l 
,011 dmYn 


0188 C27901 
1 1 2 
r l o o ~ lnnd o f b u f f s ? ? 
*,l.ll., 


0112 C l 
0103 FEOD 
0115 CllEOL 


I?. . 
i.r..r 
rod. 
2.,0' 


mz 
.rro, 
;*..,.,I 
l f n o t 


.I*. 
I l . d " 
, t o . 
. " O l h l . 
r e c o l d 


i*..f*....f...t...*....*...*..1.*..*..*. 


no,", 
i 
no, th. 
."lt co...nd, 
.."do. 
ur,,. 
r.ro 
,111, 


".I 
I F ' 
- 


m r 
n o t , 


i 
t h x r IS 
tando. 
r i l l b u f t s r 


1x1 
dtdatmr, 


c a l l 
v r l n r 
idat. 
rrorrl 


I U 1 
Cll27 
Bur t o 127 chara0111s 


L x l 
h 8 b u t f 
i d l l l l n a t l o n 


rlDDIL: i r e a d n e x t r h a r a r t c r l o b u r l 


r u s h 
b 
is.". 
rountrr 


P U I h 
h 
I".", d.rt,nat,.n 


-11 
( ~ l r h r i c h a r a c t l r l o 


0 
. 
h 
, r . , t . r . c . u n t . . 


P O I 
b 
i t ~ s t o ~ ~ 
nnx% t o fill 


r r l 
o r 
;end o f I l n r ' 


rz 
erlllo.L 
i 
n o t e n d . It.,. 
rh.r.ct.r 


no" 
m t a 


r n x 
h 
in*", 
t o f 1 1 1 


dl, 
C 
i.."",.. 
I 0 . S 
do"" 


i n 2 
rl.0.1 
:en* 
0 , b",,*.? 
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.rl.o.l: 
i 
end Of rn.4 
1.o.1 
llOI. 
00 


OIBE 3600 
I V I 
1 1 0 


- 


I 
YIII. t h e P ~ C O P ~ 
t o .ellot.d 
r n c o l d n u n b e r 


OlCO QEZB 
. u l 
C.YIIIZ~ 


OlCZ llSCOO 
1x1 
d l l r b 


OlCF FESZ 
0101 CZFFOl 
- 


c a l l 
bdos 


0 , . 
I 
;ell., 
Cod. 
2.r.v 


rnr 
*,PO, 
!.*5sa,= 
,f 
"0, 


r.. 
,,ad, 
i f D l I.Dlh.r 
,.cord 


.................................................... 
n o t , : 
i 
n o t . 
ur,,, 
.or*and, 
,.ad 
rrcold' 


rr. 
' R ' 


J.2 
eP.0, 
I S K X P $1 "0, 


i 
?.ad 
random r e e o l d 


."I 
c , r r . d r 


1 x 1 
d,,Db 
- 
OLD9 COO500 
c a l l 
b d o l 


OLDC 1 7 
or. 
a 
ireturn o o d t 0 0 1 


0100 CPFFOl 
J n l 
e r r 0 1 
- 
I 
, l a d was I Y D C ~ I I ~ Y ~ I w l l t e 10 r o n r o l r 


OlEO C01502 
c a l l 
r r l f 
i n l v l l n l 


01E3 OE6O 
IYI 
~ 1 1 2 8 inax lZB n h l r a r t l r r 


OlE5 218000 
1x1 
h e b u f f 
I n e x t Io #*I 
- 
"loo.: 


OlEB 7E 
*." 
a,. 
I"*", c h a r . o l l r 


01E9 23 
~ n r 
h 
i n r x t t o , ~ t 


OLEO E67F 
an! 
71h 
ImnsK . = P i t " 
- 
O I E C C41101 
r z 
r e a d * 
ifll I n l t h l l 00n.and 
1 f 00 


OlEF CS 
rush 
b 
i l i u ~ 
counter 


OlFO E5 
push 
h 
i r a u e n e x t t o #.t 


OlFl FEZ0 
c 
' ' 
l 9 r a ~ h ! o V 
_ 
01F3 D40EOZ 
.no 
r u t n h r 
i s L l r o u t r u t I) " 0 % 


01F6 E l 
P I . 
h 


- 
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error: 


OIFF IIUFOZ 
1x1 
deev~rns, 


0201 CD3lO2 
1.11 
r r l n t 


0205 C34101 
J....... 


I .................................................... 
8. I* "tll,," 
,ubr.utrn.. 
f o r 0ll"SOll 
110 


8 . 
/ 
* 
. 
. 
. 
. 
. 
. 
. 
. 
o 
. 
. 
. 
. 
. 
. 
. 
* 
. 
* 
. 
. 
l 
. 
. 
. 
* 
. 
. 
. 
. 
* 
. 
. 
. 
. 
* 
* 
. 
. 
. 
* 
. 
* 
. 
. 
. 
. 
. 
. 
. 


,.t.h,l 


;,.ad 
n e x t consol. 
ohararr.r 
l o a 


0208 OEOL 
nu1 
c $ c o n l n r 


0200 CDOSOO 
o a l l 
bdas 


0200 C 9 
111 


8 
P U I I h l i ............................. 


020E OE02 
IVL 
c eeonout 


0210 5F 
IOY 
I * . 
i c h a r a c t l l I0 l l n d 


0211 CDOSOO 
c a l l 
bdos 
Isend c h a l a l t e r 


0214 C9 
PI* 


i 
r r l f : 


isend c a r r i a g e r n t v r n l l n r f*.d 


0215 3EOD 
. u l 
a9.r 
1111rxa<@ ~ s t u l n 


0217 CIIOEOZ 
0.11 
l u t c h l 


O 2 l l 3EO0 
. u l 
a11f 
i l 1 n 1 f e e d 


02IC C O O E O I 
1-11 
l u t c h r 


O2lF CS 
p e t 


.a,.*, 


ir.ad 
and v a r w f r l r s r n c 


0220 I l F l O I 
1x1 
d+rDnbuf 


0223 OEOl 
""I 
Ctl.,,,", 


0225 COOS00 
rail 
bdos 


OZZU 111303 
l x l 
d t r f n o b 


0220 OE88 
.ui 
o e ~ a ~ s s f 


022D COOS00 
1.11 
bdo. 


0230 C9 
?st 


I 
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- 
.,,nt, 


i r r l n l t h e b u f f r r a d d r l r r l d br d. 
u n t l l S 


023, 
05 
r u s h 
d 


0232 CDl502 
1.11 
r r l f 
- 
023s 0 1 
PO. 
d 
in*" I,". 


0236 OEOS 
rul 
~ + l l l r l n l 


0238 CDOSOO 
c a l l 
bdar 
i ~ r l n t 
t h l s l r l n # 


i 
10""..d 
1,nr 
I. 
r r e 5 e n t l I"." 
I t 


O2Ol OEOO 
."I 
0 1 0 
;.,all 
Y l l h 00 


O24E 210000 
l 
x 
~ 
h f 0 
I 
0000 


O24F 1IF302 
1.i 
d e ~ a n l l n i o o r r a n d l l n l 


0252 1P 
r n d c : 
l d a x 
d 
!next command c h a r a c t e r 


0253 13 
1.1 
d 
i t 0 n e x t oo...nd 
r o r l t r a n 


01511 117 
a 
a 
;cannot be .nd 
o f command 


0255 CB 


i 
n o t r.ro, 
nu..rir' 


0256 D630 
l u l 
'0' 


0258 FEOL) 
r r l 
LO 
; c a r r y ~f nurlrlr 


025L) 027902 
rnc 
endrd 


- 
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i* fired and u a r l a b l e d a t a aria 
.................................................... 
- 
OZFl 21 
conbu?: 
db 
c o n l l n 
! l e n g t h o f r a n r o l l b u f f e r 
OZFZ 
c o n l l z i d l 
1 
i r l s u l l l n l ILZ. 
a f t e l lead 


OZF3 
c o n l l n : dr 
3 2 
i l l n g t h 3 2 b u f f e r 
- 


0 0 2 , = 
c o n l l n I." 
I-o.n,,r 


You could make the following major improvements to this program to enhance rts 


operation. With some work, this program could evolve into a simple data base 
management system. You could, for example, assume a standard record sire of 128 
bytes, consisting of arbmary fields with!" the record. You could develop a program 
called GETKEY that first mads a sequential file and extram a specific field defined 
by the operator. For example, the command 


CETKEY NAMES.DAT 
LASTNAME 10 20 


would cause GETKEY to read the data bare file NAMES.DAT and extract the 
"LASTNAME" field from each record, starting at position 10 and ending at charac- 
ter 20. GETKEY builds a table in memory consisting of each particular LASTNAME 
field, along with m 16-bit record number location within the file. The GETKEY 
program then sons this list and writes a new file, called LASTNAME.KEY. Wihis llst, 
sometimes called an inverted index, is an alphabetical list of LASTNAME fields with 
their corresponding record numbers. 


You could rename the program shown above to QUERY, and modify it so that it 


reads a sorted key file into memory. W e command line mzght appear as 


QUERY NAMES.DAT LASTNAME.KEY 
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Instead of reading a number, the QUERY program reads an alphanumeric string 
which is a pantcular key to find in the NAMES.DAT data base. Because the LAST- - 


NAMEKEY llsr is sorted, you can find a particular entry quickly by performing a 
blnary search, similar to looking up a name in the telephone dlmctory. Start at both 
ends of the list and examme the entry halfway m between and, if not matched, split - 


elther the upper half or the lower half for the n u t search. You will quickly reach the 
item you are looking for, in lo@(") steps, whem you will find the corresponding 
m r d number. Fetch and display this record at the urnsole as the progam ~Uusrtates. - 


At this ~oint, you are just gemng started. With a little more work, you can allow 
a fued grouping sire, whtch differs from the 128-byte record shown above. You can 
acmmplcsh this by kccplng track of the record number as well as the byte offset - 


withm the record. Knowing the group sire, you can randomly access the record 
containing the proper group, offset to the beginning of the group within the record, 
and read sequentially until the group size has been exhausted. 
- 


Finally, you can improve QUERY considerably by allowing Boolean expressions 


that compute the set of records that satisfy several relationships, such as a LAST- - 
NAME between HARDY and LAUREL and an AGE less than 45. Dsdav all the 
. . 


mords that fir this descnptlon. Rnally, if your lirtr am gemng too big to fit into 
memory, randomly access your key files from the disk as well. 


4.4 Construction of an RSX Program 


Tbis section describes the standard prefu of a Resident System Extension (RSX) 


and illustrates the construction of an RSX with an example. (See Sectton 1.6.4 for a 
dircu~sion of how RSXs operate under CP/M 3.) RSX programs am usually written 
~n assembler, but you can use other languages if the interface between the language 
and the calling conventions of the BDOS are set up properly. 
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4.4.1 
T h e RSX Prefu 


The first 27 bytes of an RSX program mntam a standard data smcturc called the 


RSX prefix. The RSX prefix has the following format: 


s e r i a l : 
db 


stax-t: 


.imp 


next: 
db 
dw 


P I L U : 


dw 


name: 
db 
l o a d e r : 
db 
db 


0 $ 0 10 10 10 , o 


f t L ~ t 


Oc3h 
0 


0 


O f f h 


0 


'123115678' 


0 
0 10 


s t a p t O f Pro9"am 


i u m ~ 
i n s t r u e t i o n t o 
n e x t n o d u l e i n l i n e 


p r e v i o u s n o d u l e 


P L m O U L f l a g 


nonbank f l a g 


any 8 - c h a r a c t e r n a m e 


l o a d e r f l a l 
r e r e r u e d a r e a 


The only fields of the RSX p& 
that you must initialize are the rcmavc: flag, the 


nonbank: flag, and the name: of the RSX. 


For comoatib~lio wlth orcvious releases of CP/M. the send: field of the orefix is 
- 
set to rhc venal numbcr of the operanng ryrtrm by rhc LOADER modulc when the 
RSX s loaded ~ntu mcmory Thus, the addrcrr ~n locar~on 6 locates the byre follow- 
~ n g 
the vrlal numbcr of the oprratmg ryrtcm wnth or wahou, RSXs ~n mcmory. 
- 
The stan: field contains a jump insmction m the beginning of the RSX code 


where the RSX tests to see if this BDOS function call is to bc intercepted or passed 
on to the next module in line. 
- 


The ncxr field mntamr a lump tnrrrumon to the next module m the cham or the 


LOADER modulc ~f the R5X s the oldest one ~n memory. The RSX proplam must 
- 
makc ~ r r 
own 81)OS functlon callr by ullong the next enny point 
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The p m field contains the address of the preceding RSX in mcmory or location 5 
if the RSX is the first RSX ~n the cham. 
- 


The remove: field conmls whether the RSX is removed from mcmory by the next 


call to the LOADER module via BDOS function 59. If the remove: flag is OFFH, the - 
LOADER removes the RSX from memory. Note that the CCP always calls the 
LOADER module during a warm start operation. An RSX that remains in memory 
past warm start because its remove: flag rs zero, must set the flag at t t s termination - 
to ensure m removal from memory at the following warm start. 


The nonbank: field controls when the RSX is loaded. If the field 8s OFFH, the 


LOADER only loads the module into memory on nonbanked CP/M 3 systems. - 
Otherwise, the RSX is loaded into memory under both banked and nonbankcd vcr- 
sions of CP/M 3. 
- 


The loader: flag identifies the LOADER RSX. When the LOADER module loads 
an RSX into memory, it sen rhls prefix flag of the loaded RSX to zero. However, the 
loader: flag m the LOADER'S orefix contains OFFH. Thus. this flaz identifies the last 
RSX in thlchain, which is al&ys the LOADER. 


4.4.2 Example of RSX Uw 


These two sample programs illusrrate the use of an RSX program. The first 
program, CALLVERS, prints a message to the console and then makes a BDOS 
Function 12 call to obtain the CP/M 3 version number. CALLVERS repeats this 
sequence five times before terminating. The second program, ECHOVERS, 1s an RSX 
that inte-rs 
the BDOS Function 12 call made bv CALLVERS. ortnrs a second 
. . 


masage, and returns the version 0031H to CALLVERS. Although thls example is 
simple, it illustrates BDOS function interception, stack swapping, and BDOS function 
calls within an RSX. 
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i CnLLUERs .ro,ram 


0003 . 
b d o r 
e y u 
5 
i e n t r y r o l n t 101 8003 


0009 = 
. I t s % ? 
I q U 
9 
i .rlnt 
r t r r n l functlon 


OOOC . 
uer, 
I." 
12 
i It, V l l l l O " runo,,on 


OOOD : 
II 
I." 
Odh 
i C.?,..,~ 
I e t Y l " 


OOOA = 
11 
r.u 
Oah 
i Ilnl fled 


0100 
1 1 , 
LOOh 


0100 IS05 
nu, 
d f5 
i P~rfoln 5 t l n l l 


0102 05 
IDDI: 
ru$h 
d 
I I="@ COYOIG~ 


0103 OE09 
I V L 
c e l r % r l r 


010s L!IEOI 
I X Z 
dlnLl8mll 
I v r t n t " a l l n t s n ( e 


0108 ED0500 
call 
b d o r 


0108 OEOC 
mu, 
v s u e r s 


0100 COO500 
call 
b d D I 
i t l Y L O # I t U e l s l O n . 


I CRLLVERS YLII l n t r r c r r t 


0110 70 
.ow 
a , , 


0111 3Z3aOL 
It. 
C u r V I P 5 


0114 01 
P O ? 
d 


OllS L5 
d l , 
d 
i d..,.*."l 
c o u n t e r 


011s CZ0201 
*nz 
IllD. 


OltS OEOO 
nu, 
010 


OllU C30500 
dnr 
b d o r 


CIII$.l,i 


OllE 00012111ZA 
db 
ortlf~'tt.1 CaLLUERS **a* )' 


0130 00 
rurucrr d b 
0 


0135 
end 


i ECHOVERS REX 


000s = 
.I%,,", .." 
9 
: St,,", 
r r l n t functr." 


OOOP = 
r r 
I." 
O d h 


0 0 0 ~ 
= 
If . 
Oah 


RSX PREFIX STRUCTURE 


0000 0000000000 
db 
0lOtOlO.OtO 
i roo. 
111 1.r1.1 
"U.bll 


0006 C31U00 
_I.. , t e s t 
8 be,," 
of ~?o,rarn 


0009 C3 
n e x t : 
db 
Oc3H 
i JUI. 


0001 0000 
d u 
0 
i next rodul. !n llnr 


OOOC 0000 
r r e u : 
du 
0 
i r r e u ~ o u r n o d u l e 


OOOE FF 
renou: 
db 
Offh 
I r e l o u l < l a # r e t 


OOOF 00 
nonbn": 
d b 
O 


0010 PSP3c381F5B 
d b 
'ECWOVERS' 


0019 000000 
d b 
O 1 O f O 


0 DIGITAL RESEARCH''" 


4-23 


4.4 
Construction of an RSX Program 
CP/M 3 Programmer's Guide - 


0027 3 9 
dad 
r r 


0028 225aOO 
; I.". 
I,.CL 


l h l d 
r e t l s t a c u 


0021 117800 
1x1 
I.tlocSrtaol 


OOZE OE09 
l u x 
I # r l l l l n l 


0030 113E00 
0033 coogoo 


1x1 
d.t.51smsl 
i p r i n t ~ ~ s s a ~ e 


"a11 
n-xt 
8 0.11 
DDOS 


0036 215100 
l h l d 
r.t$slaol 
i , e l t o , . 
UIII 
s1aoU 


0039 F9 
r r h l 


0031 2l3100 
1x1 
he0031h 
i l l t u l n u # r r l o n number 
- 


0030 C 9 
I l t 


- 
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You can prepare the above programs for execution as follows: 


1. Assemble the CALLVERS program using MAC as follows: 


MAC CALLVERS 


2. Generate a COM file for CALLVERS with HEXCOM: 


HEXCOM CALLVERS 
3. Asrmble the RSX program ECHOVERS using RMAC: 


RMAC ECHOVERS 
4. Generan a PRL file using the LINK command: 


L I N K ECHOVERS COP1 


5. Rename the PRL file to an RSX file: 


RENAME ECHOVERS.RSX=ECHOVERSlPRL 


6. Generate a COM file with an attached RSX using the GENCOM command: 


CENCOM CRLLVERS ECHOVERS 
7. Run the CALLVERS.COM module: 


CALLVERS 
The message 
**** CaLLVERS +sir 
followed by the message 
**** ECHOVERS **** 
appears on the screcn five times if the RSX program works. 


End of Section 4 
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Appendix A 
- 


System Control Block 


The System Control Block (SCB) is a CP/M 3 data s m c ~ r e 
located in the BDOS. 
- CP/M 3 uses this region primarily for communication bmveen the BDOS and the 


BIOS. However, it is also available for communication bmvecn application pm- 
grams, RSXs, and the BDOS. Note that programs that access the S p m n Control 
Block arc not version indcpndmt. They can run only on CP/M 3. 
- 


The following list describes the fields of the SCB that are available for access by 
application programs and RSXs. The location of each field is described as the offset 
- from the start addreas of the SCB lsce BDOS Function 491. The RWRO column 


lndlcates d the SCB field s Read-Wnn or Read-Only 


- 
Table A-1. SCB Fields and DdStionl 


r Offin I 
RWIRO 
I 
Definition 
I 


Reserved for aptem use. 
I 
BDOS Version Number. 
I 
Reserved for user use. Use these four bytes for your 
own flags or data. 


Reserved for system use. 
I 
Program Error Return Code. This 2-byte field can be 
used by a program m p-r 
an error code or value to a 


chained program. CP/M 3's conditional command facil- 
ity also uses this field to determine if a pmgram me- 
a n s successfully. The BDOS Functron 108 (GetlSn 
Progrsm Return Code) ia used to getlsn this value. 


~eservcd for system use. 
I 


- 
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Table A-1. (continued) 
- 


I Offset I RWIRO I 
Ddnition 
I 


Console Wldth. This byte wntalns the number of wl- 
urns, characters per Ime, on your console relative to 
zero. Most systems default this value to 79. You can 
set this default value by using the GENCPM or the 
DEVICE utility. The console wtdth value is used by the 
banked version of CP/M 3 in BDOS fundon 10. 
CP M Yr conrolc rd~nng tnput hnnnon Nore r h a ~ 
ryp- 


top, a character nnto rhc last pusmon of the rcmn, ar 
spccded by the Conrulc Wndth field, mus nor cauv 
the terminal to advance m the next line. 


Console Column Position. This byte wntains the cur- 
rent console column position. 


CollsoIe Pam Length. This byte contains the page Im&, 
Ilnc5 per page, of your conrole Most syqtrmr dcf.wlr 
thlr value to 24 Inner per page lhtr default value may 
bc chanecd by urme the CFNCPM or thr DEVICE utd- 
ity (sce;he 
CP/MPI~S (CP/M Version 3) Operating 
System User's Guide). 


Reserved for system use. 


Redirection flags for each of the five logxcal character 
devices. If your system's BlOS suppons assignment of 
logical devices to physical devices, you can direct each 
of the five logical character devices to any combination 
of up to 12 
devices. The 16-ba word for each 


device represents the following: 
Each bit represents a physical device where bit IS wr- 
responds to device zero and bit 4 corresponds to devlce 
11. BIB zero through 3 are reserved for system use. 
You can r c d i m the input and output logical devices 
with the DEVICE wmmand [see CP/M Plus (CP/M 
Version 3) Oper#ting System User's Gutde). 
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Table A-1. 
(continued) 


Offset I RWIRO 
Definition 


22 - 
23 
RW 
CONIN Redirect~on Flag. 


24 - 
25 
RW 
CONOUT Redirection Flag. 


1 26 - 
27 
RW 
AUXIN Redirmion Flag. 
I 


1 28 - 
29 
RW 
AUXOUT Redirection Flag. 
I 


( 


2A - 
2B 
RW 
LSTOUT Redirection Flag. 


2C 
RW 
Page Mode. If this byte is set to zero, some CP/M 3 
utilities and CCP built-in commanda display one page 
of data at a time; you display the next page by pressing 
any key. If this byte is not set to zero, the system dis- 
plays data on the screen without stopping. To stop and 
start the display, you can press CTRLS and CTRL-Q, 
respectively. 


RO 
Reserved for system use. 
I 
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Determines if CTRL-H is interpreted as a rubldcl char- 
acter. If thrs byte is set to 0, then ClXL-H is a back- 
space character (moves back and deletes). If this byte is 
st m OFFH, then CTIU-H is a mbldd draracter, echoes 
the dcleted character. 


Urrrmtnrr rf ruh dcl IS rnrcrprcred rr CTRI.-H rharac- I 
rcr. If this bye a m to 0. thm rub dcl rchm thc dclned 
character. If thtn byto ts xt 10 OFt, thm rub dcl tr mro- 
pmed as a CIT(L-H character (move back and deletes). 


Reserved for system use. 
I 


Console Mode. This is a 16.bit system parameter that 
determines the action of certain BDOS Console VO 
functions. (See Sectlorn 2.2.1 and BDOS Function 109, 
GcrlSet Console Mode, for a thorough explanation of 
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RW 
Output delimiter character. The default output delim- 
iter character is $, but you can change this valuc by 
using the BDOS Function 110, Getkc Output Delimiter. 


Table A-1. 
(continued) 


RW 
List Output nag. If this byte is set to 0, console output 
is not echoed to the list dorice. If this byte is set to 1 
console output is echoed m the list device. 


Offset 


39 - 
38 
RO 
Reserved for system use. 
I 


RWIRO I 
DqSnition 


3C - 3D 
RO 
C m t DMA Add- 
?ha a d h wn be ur by RDOF 


Funnnon 26 (Scr D.MA Addmlrl Thc CCP ~ n ~ r ~ a l l z r s 
th~, valuc to 0080H. BDOS tuncnon 13, Rrrn Dtrk 


35 - 
36 
RO 
Reserved for system use. 


System, also sen the DMA address to 0080H. 
I 
3E 
RO 
Currmt Disk. This byte contains the cumntly sclmed 
default disk number. This value ranges from 0-15 cor- 
responding to drives A-P, respectively. BDOS Function 
25, R a m Current Disk, can be used to determine the 
current disk value. 


1 3F - 
43 
RO 
Reserved for system use. 
I 


I 


RO 
Curmt U~cr Number. This byte contains the currat 
user number. This value ranges from 0-15. BDOS Func- 
tion 32, SetIGct User Code, can change or interrogate 
the currently active user number. 


1 45 - 
49 
RO 
Reserved for system use. 
I 
4A 
RW 
BDOS Multi-Smor Count. This field is s n by BDOS 
Function 44, S a Multt-Smor Count. 


- 
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Table A-1. (conhoed) 
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Offset 
1 
RWIRO ( 
Defhition 


RW 
BDOS Error Mode. This field is s n by BDOS Function 
45, Set BDOS Error Modc. 
If this byte is set to OFFH, the systcm returns to the 
current program without displaying any error messages. 
If it is set m OFEH, the system displays ermr messages 
before murning to the current program. Otherwise, the 
rystcm terminates the program and displays error mes. 
sages. See description of BDOS Function 45, S n BDOS 
Error Mode, for & d o n of the different error modes. 


RW 
Drive Search Chain. The lint bytc contains the drive 
number of the first d"w in the chain, the second byte 
contains the drive number of the second drive in the 
chain, and so on, for up to four bytes. If less than four 
drives arc to be searched, the next bytc is set to OFFH 
to signal the end of the search cham. The drive values 
rang; kom 0-16, where 0 corresponds to the default 
drive, while 1-16 corresponds to drives A-P, respec- 
tively. The drive search chain can be displayed or set 
by using the SETDEF utility (see CP/M Plur (Vmion 3) 
Operating System Urn's Guide). 


RW 
Temporary File Drive. This bytc contains the dive 
number of the temporary file drivc. The drivc number 
ranges from 0-16, where 0 cornponds to the default 
drive, while 1-16 cornsponds m drives A-P, mpctivdy. 


RO 
Error drive. This byte contains the drivc number of the 
selected drive when the last physical or enended error 
occurred. 


RO 
Reserved for system use. 


O DIGITAL RESEARCH' 


A-5 


A 
Syrtcm Control Block 
CP/M 3 Programmer's Guide 


57 
RO 
BDOS Flags. Bit 7 applies to banked systems only. If 
bit 7 is set, then the system displays expanded error 
messages. The second error line displays the function 
number and FCB information. (See Section 2.3.13). 
Bit 6 applies only to nonbanked systems. If ba 6 is set, 
. 
indicates that GENCPM has specified single alloca- 
tion vectors for the system. Otherwise, double alloca- 
tlon vectors have been defined for the system. Function 
98, Free Blocks, returns temporarily allocated blocks to 
free space only if bit 6 is reset. 


1 58 - 
59 
RW 
Date in days in binary since 1 Jan 78. 
I 


I SA 


RW 
Hour in BCD (&digit Binary Coded Dedmal). 
I 


1 5B 


RW 
Mnnutes in BCD. 
I 


I 5c 
RW 
Seconds in BCD. 
I 


5D - 
5E 
RO 
Common Memory Base Address. This value e zero for 
nonbanked systems and nonzero for banked systems. 


I SF - 
63 
RO 
Reserved for svstem use. 
I 


End of Appendix A 


Appendix B 
PRL File Generation 


B.1 PRL Format 


A Page Relocatable Program has an origin offset of lOOH bytes that is stored on 
disk as a file of type PRL. ?he format is shown in Table B-1. 


Table B-1. PRL Pile Format 


Address 
Contnrtr 


0001-0002H 
Pmgram size 


1 0004-000SH 
Minimum buffer requirements (additional memory) 
I 


0006-00FFH 
Currently unused, reserved for fumre allocation 


0100 + Program size = Start of bit map 


The bit map is a string of bits identifying those bytes in the source code that 
require relocauon. There is one byte in the bit map for every 8 b w s of source code. 
The most significant bit, bit 7, of the k t byn of the bit map m k t e s whether or 
not the fist byte of the source code requires relocation. If the bit is on, it indicates 
that relocarion rs rcqulrcd. The next bi;, bxt 6, of the first byn corresponds to the 
second byte of the source code, and so forrh. 


B 
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8.2 Generating a PRL 


The referred technique for generating a PRL file is to use the CP/M LINK-go', 


which can generate a PRL file from a REL relocatable object file. This technique is 
described in the Progmmmer'r Utilities Guide for The CP/M Fmnily of Opnaring 
Syrtemr. A sample link command IS shown below. 


End of Appmdtx B 
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Appendix C 
SPR Generation 


System Paze Relocatable, SPR. files are similar in format to PRL files exccot that 


SPR file have an origin offset of OOOOH (see Appendix B). SPR Files are prov;ded as 
part of the standard CP/M 3 System: the resident and banked portions of the banked 
BDOS. named RESBDOS3.SPR and BNKBDOS3.SPR and the nonbanked RDOS. 
~ ~- -- .. 


named BDOS3.SPR. The customzed BIOS must also be generated m SPR format 
before GENCPM can create a CP/M 3 svstem. The BlOS SPR file i. n2mrA 
. . . . . . . . . 
. .- - 


RNKBIOS3 SPK ror hanked ryrrmand B ~ S ~ . \ P R 
for ninbankcdrynrmr. A dnmled 


dacuwon of the gcncrarlon of BIOS3.SPR or BNKBIO\I 5PR Is prov~dcd ~n thc 
CP Af Plw ICr M \'erston 3, Oppror8ng S>rtem .S)rrem Gutd* 


The method of generating an SPR is analogous m that of generating a Page Relo- 


catable Program (described in Appendix 8) with the following excepttons: 


If LINK-80 is used, the output file of type SPR is speafied with the [os] or [b] 
option. The [b] option is used when linking BNKBIOS3.SPR. 


The code in the SPR is ORGed at OOOH rather than 100H. 


End of Appmdix C 
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ASCII and Hexadecimal Conversions 


This appendix contains tables of the ASCII symbols, including their binary, deci- 
mal, and hexadeumal conversions. 


ACK 
acknowledge 
FS 
file separator 
BEL 
bell 
GS 
group separator 
BS 
backspace 
HT 
horizontal tabulation 
CAN 
cancel 
LF 
line-feed 


CR 
carriage return 
NAK 
"egati~e adrnowledge 


DC 
device control 
NUL 
null 


DEL 
delete 
RS 
record separator 


DLE 
data link escape 
Sl 
shik m 


EM 
end of medium 
SO 
shift out 


ENQ 
enquiry 
SOH 
start of head~ng 


EOT 
end of transmission 
SP 
space 
ESC 
escape 
STX 
start of t a t 


E l 3 
end of transmisrion 
SUB 
substitute 


En[ 
end of text 
SYN 
synchronous idle 
FF 
form-feed 
US 
unit separator 


V T 
vertical rabulatlon 


Table D-1. ASCII Symbols 
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Symbol I 
Meaning 
Symbol 
1 
Meontng 
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Table D-2. ASCII Comvm~ion Table 
- 


I Binow 
/ 
Decimol 
I 
Hex.decimal 
1 
ASCII 
I 


00 
NUL 


01 
SOH (CTRL-A) 


02 
STX (CTRL-B) 


03 
ETX (CTRL-C) 


04 
EOT (CTRL-D) 
05 
ENQ (CTRLE) 


06 
ACK (CTRL-F) 


07 
BEL (CTRL-G) 


08 
BS 
(CTRL-H) 
09 
HT (CTRLI) 


0 A 
LF 
(CTRL-J) 


OB 
fl (CTRL-K) 


OC 
FF 
(CTRL-L) 
OD 
CR 
(CTRL-M) 


OE 
so 
(CTRL-N) 


OF 
SI 
(CTRL-0) 


10 
DLE (CTRL-P) 


11 
DCl (CTRL-Q) 


12 
DC2 (CTRL-R) 


13 
DC3 (CTRL-S) 


14 
DC4 (CTRL-T) 


I5 
NAK (CTRL-U) 


16 
SYN (CTRL-VJ 


17 
ETB (CTRL-W) 
18 
CAN (CTRL-X) 


19 
EM (CTRL-Y) 


1A 
SUB (CTRL-Z) 


IB 
ESC (CTRL-[) 


1C 
FS 
(CTRL-\) 


ID 
CS 
(CTRL-I) 


1E 
RS 
(CTRL.") 


IF 
US 
(CTRL,) 


20 
(SPACE) 
21 
22 
23 
# 
24 
$ 
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Tnblc D-2. (continued) 


Binory 
I 
Decimal 
I 
Hexndecimnl 
ASCII 
1 
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End of Appendiz D 
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Table D-2. (conrinucd) 
- 


Binnry 
1 
Decimal 
I 
Hcxodeciml 
ASCII 


1100111 
103 
67 
g 


llOl000 
104 
68 
1101001 
105 
69 
1101010 
106 
6A 
j 


1lOlOll 
107 
68 
1101100 
108 
6C 
I 
1101101 
109 
6D 
m 


1101110 
110 
6E 
n 


1101111 
111 
6F 
1110000 
112 
70 
P 


lllO001 
113 
71 
q 


1110010 
114 
72 
r 


1110011 
11s 
73 
J 


1110100 
116 
74 
t 


1110101 
117 
75 
1110110 
118 
76 


lIlOlll 
119 
77 
W 


1111000 
120 
78 
1111001 
121 
79 
Y 
1111010 
122 
7A 
1111011 
1 U 
70 
( 


1111100 
124 
7C 


125 
7D 
I 
1111101 
1 


1111110 
126 
7E 
- 


1111111 
127 
7F 
DEL 
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Table E-1. BDOS Function Summay 


Frmnion 1 
Function Nome 
I lnput Panzmeterr 1 
Returned Vaher 


0 
System Reset 
none 
none 


1 
Console Input 
none 
A = char 


2 
Console Output 
E = char 
A = OOH 
3 
Auxiliary Input 
none 
A = char 
4 
Aux~liary Output 
E = char 
A = OOH 
5 
List Output 
E = char 
A = OOH 
6 
Dmct Consolc I10 
E = OFFW 
A = charlstatusi 


OFEW 
none 
omw 
char 
7 
Auxiliary Input 
none 
A = OOIOFFH 


Status 


8 
Auxiliary Output 
none 
A = OOIOFFH 


Status 


9 
Prlnt String 
DE = .String 
A = OOH 
10 
Read Console Buffer 
DE = .Buffer0 
Characters in buffer 


11 
Get Console Status 
none 
A = 00101 
12 
Return Versron Number none 
HL = Version (0031H) 


13 
Reset Disk System 
none 
A = OOH 
14 
Select Disk 
E 
= Disk 
A = Err Flag 


Open File 
Close Filc 
Search for First 
Search for Next 
Delete File 
Read Sequential 
Write Sequential 
Make Filc 
Rename File 
Rcturn Logln Vector 
Return Current Dlsk 


Number 
DE = .FCB 
A = Dir Code 
DE = .FCB 
A = Dir Codc 


DE = .FCB 
A = Dlr Code 


none 
A = Dir Code 
DE = .FCB 
A = Dlr Code 
DE = .PCB 
A = Err Codc 
DE = .PCB 
A = Err Codc 
DE = .FCB 
A = Dir Code 
DE = .FCB 
A = Dlr Code 


none 
HL = Login Vector 


none 
A = Cur Disk# 
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25 
Return Current Dl& 


26 
Set DMA Address 
27 
Gtt AddrlAIIx) 


28 
Write Protect Disk 
29 
Get R/O Vector 


30 
Set File Amibutcs 


31 
Get Addr(DPB1 


32 
Set/Get User Codc 


Tnblc E-1. 
(mntinuedl 


33 
Read Random 
34 
Write Random 
35 
Compute File Sire 


36 
S a Random Record 


37 
Reset Drive 


Retunzed Values 


Access Drive 
F m Drive 
Write Random with 
Zero Fill 
Test and Write Record 
Lock Record 
Unlock Record 
Set Multi-remr Count 
Set BDOS Error Mode 


Input Pmmmtnr 
hncnon 


Get Disk F m Spaa 


Flmction Name 


Chain to Program 
Flush Buffers 
GetSa System 
Control Block 
Direct BlOS Calls 
Load Overlay 
Call Resident Sntem 


"0°C 
DE = .DMA 
none 
none 
none 
DE = .FCB 
none 
E = OFFW 


user number 
DE = .FCB 
DE = .FCB 
DE = .FCB 


DE = .FCB 
DE = Drive 
Veaor 
none 
none 
DE = .FCB 


DE = .FCB 
DE = .FCB 
DE = .FCB 
E = # Sectors 
E = BDOS Err 
Mode 
E = Drive 
number 
E = Chain Flag 
E = Purgr Flag 
DE = .SCB PB 


DE = .BIOS PB 
DE = .FCB 
DE = .RSX PB 


A = Cur Disk# 
A = OOH 
HL = .Allot 
A = OOH 
HL = R/O Vector 
A = Dir Codc 
HL = .DPB 
A = Curr Used 


OOH 
A = Err Codc 
A = Err Code 
m, rl, c2 
A = Err Flag 
m, rl, r2 
A = OOH 


A = OOH 
A = OOH 
A = Err Code 


A = OFFH 
A = OOH 
A = OOH 
A = Return Code 
A = OOH 


Number of Free Sectors 
A = Err Flag 
A = OOH 
A = Err Flag 
A = Rrmmed Bpe 
HL = Rrmrned Word 
810s Rrmrn 
A = Err Code 
A = Err Codc 


Extension 


Note: . indicates the add- 
of 
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Funcnon I Function Name 
I hput Parorneterr I Rmrrned Valuer 


98 
Free Blo&s 
none 
A = Err Flag 


99 
Truncate File 
DE = .FCB 
A = Dir Code 
100 
Set Directory Label 
DE = .FCB 
A = Dir Code 
101 
Return Directory 
E = Drive 
A = Dlr label data bpe 


Label Data 


102 
Read File Date Stamps 
DE = .FCB 
A = D a Code 
and Password Mode 
103 
Write File XFCB 
DE = .FCB 
A = Dir Code 


104 
Set Date and Time 
DE = .DAT 
A = OOH 


105 
Get Date and Ttme 
DE = .DAT 
Date and Time 
A = seconds 
106 
Set Default Password 
DE = .Password 
A = OOH 


107 
Return Serial Number 
DE = .Serial # 
Serial Number 


field 


108 
Get/Set Program 
DE = OFFFFW 
HL Program Ret Code 
Return Code 
Code 
none 


109 
GetISet Console Mode 
DE = OFFFFW 
HL = Console Mode 
Mode 
none 


110 
GetSet Output 
DE = OFFFFW 
A = Output Delimiter 
Delimiter 
E = Delimiter 
none 
111 
Print Block 
DE = .CCB 
A = OOH 


112 
List Block 
DE = .CCB 
A = OOH 


152 
Pane Filename 
DE = .PFCB 
See definition 


Note: . indicates the address of 
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Foreword 


CP/M' 
3 , also marketed as CP/M PlusTU 
is a single-console 
- 
operating system for &bit machines that use'an Intel- 8080 8085, 
Or 2i10gQ 280- CPU. 
CP/H 3 is upward-compatible *i;h 


predecessor, CP/M 2, and offers more features and higher 
than CP/M 2. This manual describes the steps neoessary to create or 
- 
rnodlfy a CP/M 3 Basic Input Output System (BIos1 tailored for a 
specific hardware environment. 


- 


Section 1 of this manual is an overvlev of the component 
nodules of the CP/M 3 operating system. 
Section 2 provldea an 
overview of the functions and data structures necessary to write 
interface nodule between CP/M 3 and specific hardware. 
section 3 
- 
contains a detailed description of these functions and data 
structures, followed by instructions to assemble and link the 
distributed nodules with your customized modules. 
Section 4 
describes the nodular organization of the sample CP/M 3 BTOS on your 
- 
distribution diskette. 
Section 5 documents the procedure to 
qeneraFe and boot Your CP/M 3 system. 
Section 6 is a sample 
debugging session. 


The appendixes contain tables, and sample BIOS modules you can 
- 
use, or study and modify. 
Appendix A discusses removable medla 
drives. AppendixB discusses automatic density support. ~ p p e n d l ~ 
c 


describes how CP/M 3 differs from CP/M 2. 
Appendix o shows the 
format of the CPM~.SYS file. 
- 
Appendixes B through A are listings of the assenbled souroe 
code for the four hardware-independent lwdvles of the sample BTOS. 
appendix E is the kernel module to use when creating a modular BTOS 
in the form of the distributed sample. Appendix P shown the system 
- 
Control Block. Appendix G is a table of equates for the baud rate 
and mode byte for cheraotsr 1/0. 
Appendix H contains the macro 
definitions you can " 6 0 to generate some of the CP/M 3 disk data 
S t r Y C t U r e S . 
Appendix I lists the assembled source oode for the aix 


BIOS modules that depend on the Altos@ 8000-15 Computer System 
- 
hardware. 
It also contains a sample Submit file to build a BIos. 


- 


~ppendires J and K are tabular summaries of the public entry 


points and data items in the modules of the sample BIOS. Finally, 
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Section 1 


CP/M 3 Operating System O v e ~ e w 


This Beckion is an overview of the CP/M 3 operating system 
rith a description of the eyeten components and how they relate th 
eaah other. 
The section includes a discussion of memory 
configurations and supported hardware. The last portion eumariaes 
the creation of a customired version of the CP/M 3 Basic Input 
Output System (BIOSI . 


CP/n 3 provides an environment for program developent and 
execution on oomputer systems that use the Intel 8080 8085,ar z80 
mioroProoessor chip. 
CP/M 3 provides rapid acces: 
to data and 


programs throogh a file structure that supports dynamic allocation 
of apace for sequential and random access files. 


CP/M 3 supports a maximum of sixteen logisal floppy or hard 
disks With a storage capacity of up to 512 megabytes each. 
=he 


maximum file size supported is 32 megabytes. You can configure the 
number of directory entries and block size to satisfy various user 
Deeds. 


CP/M 3 is sUPPlied in two versions. 
One version anonnrrs 


The nonbanked aystem requires 8.5 kilobytes of memory 


space for your customized 810s. It can execate in a ninimun.oP1;; 
kilobytes of memory. 


CP/H 3 residee in the file CPH~.SYS 
which is loaded into 


m m r y by a system loader during system ini;ialization. 
he system 


loader resides on the first two tracks of the system disk. CPM~.SYS 
contains the distributed BDOS and the cuseomized BIOS. 


The CP/M 3 operating system is distributed on two aingle- 


density, single-sided, eight-inch floppy disks. 
Digital ~ 
e 
s 
~ 
~ 
~ 
~ 
h 
supplies a sample 6109 that is configured for an Altos 8000-15 
microcomputer system rith bank-switched memory and two single- 
density, single-sided, eighk-inch floppy disk drives. 
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CP/M 3 system components - 


he CP/M 3 operating system consists of the following three 
:;::;;:;g :;:t2::;:;, 
, c : ~ ~ e p ; : ~ ~ : s ~ ~ p " ~ c ~ ~ p " ~ ~ y ~ ~ ~ c ( ~ ~ ~ ~ ; . 


=he CCP is a program that provides the basic user interface to 
the facilities of the operating system. The CCP supplies sir built- 
:~e~;~~~~:rh.D'$aR.'~; 
",~r;nY:FiT~2~~*t~~dr,","HZ 
o 
: 
" 
. 
' 
. 
; 
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: 
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i 
t 
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: 
l 
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: 
" 
; 
E 
g 
r 
: 
: 
: 


from disk into the TPL for execution 
, 
~:"::".:ghet%::p:::: 
b".":::."," 
PC :;;l'i::t"::," 
;i0;69c:c :id 2: 


rrhveioal input/output routines of the BIOS. 
. . 


he 610s is a hardware-dependent module that interfaces the 


BOOS to a p a r t i ~ u l ~ ~ 
hardware environment. The 910s performs all 


physioal 110 in the system. 
610s consists of a number of 
routines that you ."st 
configure t o *upport the specifis hardware of 
the tarqet oonputer system. 


he eDos and the 610s modules cooperate to provide the CCP and 


other transient programs vith hardware-independent scsess toCP/M 3 


programs that run under CP/M 3 unchanged to aykema with different 
hardware oonfigurcitions 


he 610s load. 
the CCP into the TPA at system sold and warm 
;;r:;d :::::;~~r::L:::::a;2::2::E:?t::":;:"Y:~r:::. 


fu&tiinP, 
such as peripheral device 110. or example. ~ u u n 
LU =,I 


entry point of the erOS called by me e m s to read the next console 
input oharaoter. 


S i m l i a r ~ r l e e exist between the BDoS functions and the 610s 
- 
fmct~ons, p a r t ~ c v l a r l y for sllnple device 110. For example. when a 
translent program makes a console output functlon c a l l t o the BWS. 
the BDOS makes a console output c a l l to the BIOS. 
I n the case of 


dzsk 110, however, t h i s relatlonrhlp is more complex. 
n he BDOS 


night make many 610s function c a l l a t o perform a single B W S f l l e 
- 
110 function. 
BDOS disk 110 1s in terms of 128-byte iogzcal 


records. 610s d ~ s k 
110 IS In terns of physlcal sectors and tracks. 


me system Control Block (SCB) i s a 100-byte. decimal. CP/M 3 
- 
data structure t h a t resides in the B W S system component. 
me BDOS 


and t h e BIOS comnunlcate through f l e l d s ~n the SCB. 
he SCB 


m n t a l n n B m S f l a g s and data, CCP f l a g s and data, and other system 
mformzltlon, such as console characteristics and the current dare 
and tine. 
You can access some of the System Control Block fields 
- 
fr-m the Blos. 


Note t h a t the SCB contains c r i n c a l system paraneterr wh~ch 


r e f l e c t the current stare of the operarlng system. 
If a program 
- 
nodxfles these paranetera, the operating system can crash. 
see 


Secrlon 3 of t h i s manual, and the deacilprlon of BDOS Funct~on 
49 ~n 


the CP/M plus Programmer's ~ u l d e Lor more lntormarion on the system 
control Bloc*. 


CP/M 3 System Guide 
1.3 
Cmunication Between Modules 


Hlgn memory 


LOADER-bare 


TPA 


OOOOH 


Figure 1-1. 
General n a r y Organization of CP/M 3 


Note that all memory regions i n CP/M 3 are page aligned, which 


m a n e that they must begin on a page boundary. 
Because a page is 
defined as 256 1100H) bytes, a page bovndary always begins at a 
hexadecimal address where the low-order byte of the hex address is 
zero. 


/ 


1.4 
Banked and nonbanked Systems 


CP/H 3 is supplied in two versions: 
one for hardware that 


supports banked memory, and the other for hardware with a minimum of 
32 kilobytes of memory. 
The systems are called banked and 


nonbanked. 


BlOS Bsslc 110 System 


BDOS Bar,= DlSl ODeratlng system 


LOADER Program Loader Module 


component 0' CCP 


TPA Trannent Program Area 


CCP ~onra~ecommand 
Processor 


PAGE ZERO 


0igit.1 
~csearch 
supplies system page ~elocatsble (.SPRI files 


for both a banked BDOS and a nonbanked BDOS. A sample banked BIOS 
is supplied for you to use as an example when creating a customized 
BIOS for your set of hardware components. 


CP/M 3 System Guide 
1.4 
Banked and Nonbanked Syatems 


The following figure shows the memory organization for a banked 


eystea. 
Bank 0 and common memory are for the operating system. 
Bank 1 is the Transient Program Area, which contains the Page zero 
reglon of memory. You can use additional banks to enhance operating 
system performance. 


In banked CP/M 3 systems, CPMLDR, the system loader, loads part 
of the BDOS into common memory and part of the Boos into ~ a n k 
0. 


CPMLDR loads the 810s in the same manner. 


Figure 1-2 shows the memory organization for he banked version 
or CP/M 3. 


TOP Of memory 


{ 


HardwareOependent Buffer space 


common 


Resfden, OPerafng systsm ModuleP 


10 a , banks 


Too 0, Banked 


Memory 


- 
Figure 1-2. m e m r y Organization for Banked CP/M 3 System 


I" this iigure, the top region of memory 1s called comon 
- 
memory. 
C a m o n memory is always enabled and addressable. 
The 
Operating system is divided into two nodules: the resident portion, 
which resides in camon nemorv, and the banked oortion, which 
resides just below c o m o n memory in sank 0. 
. 
. 
- 
The shaded areas in Figure 1-2 represent the memory available 


to transient programs. 
The clear areas are used by the operating 
system for disk record buffers and directory hash tables. he clear 
area in the common region above the operating system represents 
- 
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apace that can be allocated for data buffers by GBNCPM, the CP/M 3 
system generation utility. The minimum size of the buffer area is 
determined by the specific hardware requirements of the host 
miorooomputer system. 


Bank 0, the system bank, is the bank that is enabled when CP/M 


3 is oold started. Bank 1 is the transient pragram bank. 


he transient program bank must be contiguous iron location 


zero to the top of banked memory. 
c m o n memory must also be 


~ o n t l g ~ ~ u s . 
=he other banks need not begin at location zero or have 


~ontiguous memory. 


Figure 1-3 shows the CP/M 3 memory organization when the TPU 


bank. Bank 1, is enabled in a bank-switched system. 


TOP 01 memory 


common 


Top Dl Banked 


Memory 


Low Memory 


i0OOOHi 


~ardware Dependent Buffar Space 


~es~dent 
o~erattna system Modules 


Bani 1 


ligure 1-3. 
~ l e a r y Organization with Bank Innabled 


in ~ a n k e d 
System 


he operating system switches to ~ a n k 
o or other banks when 
performing operating system funotions. 
In general, any hank 
switching performed by the operating system is transparent to the 
calling program. 


he memory organization for the nanbanked version of CP/M 3 is 


much simpler, as shown in Figure 1-4: 


- 
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Figure 1-4. 
Memory Organization in Donbanked CP/II 3 System 


In the nonbanked version of CP/M 3, memory consists of a single 
contiguous region addressable from OOOOB up to a maximum of OPPPPH, 
or 64K-1. 
The clear area above the operating system represents 


spaoe that can be allocated for data buffers and directory hash 
tables by the CP/M 3 system generation utility, GENCPH, or directly 
allocated by the BIOS. 
The minimum size of the buffer area is 
determined by the specific haldvare requirements of the host 
microconmuter system. Again, the shaded region represents the apace 
available for transient programs. 


- 
1.5 
mmry muir-nts 


Table 1-1 shows typical sizes of the CP/n 3 operating system 


components. 


The CP/M 3 banked syaten requires a minimum of two banks (8ank 


0 and Bank 11 and can support up to 16 banks of meraory. =he size of 
khe canon region is often 16K, but can be as small as 41(. 
cornon 


~ e m o r y 
must be large enough to contain the required buffers and the 


resldent (oornonl portion of the operating system, which means a 
1.5K BOOS and the cornon part of your customized BIOS. 


- 


Table 1-1. 
CP/M 3 Oprating System memory m q u i r a e n t s 


- 


CP/M 3 Version 


BDOS 
8.5K 
1.5K 
llK 


Nonbanked 
Banked 


COrnO" 
Bank 0 
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In a banked environment, CP/M 3 maintains a cache of deblocking 
buffers and directory records using a east Recently used ILRUI 
buffering scheme. =he LRU buffer is the first to be reused when the 
system runs out of buffer spaoe. The BDOS maintains separate buffer 
pools for directory and data record caohing. 


=he RSX modules shorn in Figure 1-5 are Resident system 


~xtensians ( ~ 5 x 1 
that are loaded directly below the operating system 


when included in an application or utility program. 
The Program 


~ o a d e r 
placer the RSX in memory and ohains BDOS calls through the 
RSX entry point in the RSX. 


Pigure 1-5 shows the memory organization in a typical bank- 


switched CP/M 3 Bystem. 


COMMON MEMORY ~~~ 


BANKED BlOS 3K 


,one per drive) 


BANKED BDOS 11K 


COPY OF CCP FOR 


I R U DlRECTORY 


HASHED DIRECTORY 


Opflonsl overlays 


TRANSIENT PROGRAM 
t - l 


PAGE ZERO 


BANK 0 
SANK 1 
BANK 2 


rigore 1-5. 
Ile.ory Organi=ation in Banked CP/* 3 


- 
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The banked system supports a TPA of 60R or more. The banked 
- 
portion of the operating system in Bank 0 requires at least 1 6 ~ 
of 
memory. 


In the banked system, the B W S and the BIOS are separated into 
- 
two part.: 
a resident portion, and a banked portion. The resident 


BOOS and 610s are located in common memory. 
he banked BOOS and 
BIOS are located in the operating system bank, referred to as ~ a n k 
0 


in this manual. 


The TPA extends from lOOH in Bank 1 up to the bottom of the 
resident B W S in common nemory. The banked BIOS and BDOS reside in 
Bank 0 with the directory buffers. 
Typically, all data buffers 
reside in common. 
Data buffers can reside in an alternate bank if 
the system has a ~ r n 
controller capable of transferring arbitrary 


blooks of data from one bank to another. 
Bashed directory tables 
(one per drive) can be placed in any bank except Bank 1 (TPI). 
Hashed directory tables require 4 bytes per directory entry. 
- 
~ i q u r e 
1-6 shows a typical nonbanked system configuration. 


Buffers and Hash Tales 


PROGRAM LOAOER 


- 
- 
Pisure 1-6. memory Organization in nonbanked CP/M 3 


he nonbanked CP/M 3 system requires 8.5~ of memory plus space 
- 
for theBIOS, buffers, and hash tables, allowing a TPA size of up to 
52K to 56K. depending on the size of the BIOS and the number of hash 
tables and buffers you are using. 
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1.6 
Disk organization - 


sigure 1-7 illustrates the organizatmn of a CP/M 3 system - 


disk. 


Track M 
- 


Track 0 


Figure 1-7. 
CP/M 3 S y s t w oisk Organization 


- 


1.7 
Eardware Svpeorted 


YOU can customize the BXOS to match any hardware environment 


with the follaing general characteristics. 
- 
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1.7.1 
nardrare supported by CP/* 
3 ~ a n k e d 
S y s t a 


Intel 8080. Intel 8085, or Z i l q 280 CPU or equivalent. 


I\ m ~ n t m m o f 
two and up to slxreen banks of memory vlr? rhe top 


(R-32% ~n common memory. 
sanr L must have conrlgao~s nenocy 


from address 0000" to t h e base of common memory. A reasonable 
c o n f ~ g ~ r a t ~ o n 
C O ~ S I S C S 
of tao ~ a n l s 
of 18K m each, u l r n t h e 


top 16r in common memory. 
. 
one to sixteen disk drives of up to 512 megabytes capacity 
each. 
. 
some form of ~ S C I I 
console device, usually a CUT. 


One to twelve additional character input andor outputdevioes, 
such as printers, oomunications hardware, and plotters. 


1.7.2 
Bardware supported by CP/* 
3 Wonbanked System 


Intel 8080. Intel 8085, or Z i l q 280 CPU or equivalent. 
. 
A minimum of 32R and up to 64K contiguous memory addressable 
from location zero. 


One to sixteen disk drives of up eo 512 megabytes capacity 
each. 


some form of ASCII console device, usually a CRT. 
. 
One to twelve additional input and or output devices, usually 
including a printer. 


- 


1.8 
C u s ~ i r i n g 
CP/n 3 


Digital Research supplies the B W S files for a banked and a 
- 
nonbanked veraion of CP/M 3. 
A system generation util~ty, GENCPR. 


is provided with CP/M 3 to create a verslan of the operating system 
tailored to your hardware. 
GENCPM combines the B W S and your 
customized BIOS files to create a CPH3.SYS file, which is loaded 
- 
into memory at system start-up. =he CPM3.STS file contains the BDOS 
and BIOS system components and information ind~cating where these 
modules reside in memory. 


Digital Research supplies a CP/M 3 loader file, CPMLDR, which 


YOU can link with your customized loader BIOS and use to load the 
CPM3.SYS 
file into memory. 
CPMLDR is a small, self-oontained 


version of CP/M 3 that supports only console output and sequential 
flle input. Consistent with CP/M 3 organization, it contains two 
modules: an invariant CPMLDR 800s. and a variant CPMLDR BIOS, which 
is adapted to match the has? microcomputer hardware Gvironment. 
TheCmLDR BIOS module can perform cold start initialization of 1/0 
pocts andsimilar functions. CPMLDR can display a memory map of the 
CP/M 3 system at start-up. 
This is a GENCPM option. 


The following steps tell you ha, to create a new version of 


CP/M 3 tailored to your specific hardware. 


1) Write and assemble a customized BIOS following the - 


specifications described in Section 3. 
This software 


m o d u l e m u s t c o r r e s p o n d to t h e e x a c t p h y s i c a l 
characteristics of the target system, including memory and 
p o r e a d d r e s s e s , p e r i p h e r a l t y p e s , and d r i v e - 
cha~a~teristios. 


2) Use the system generation utility, GENCPM, to create the 


CPII3.SYS file containing the CP/M 3 dlstributed 800s and - 
your ust tom zed BIOS, as described in Section 5. 


3) wriee a customized loader BIDS (LDRBIOS) to reside on the 


Systen track* as part of CPMLDR. CPMLDR loads the CPM3.SYS 
file into memory from disk. 
Section 5 
gives the - 
instructions for customizing the LDRBIOS and generating 
CPMLDR. 
link your customized LDRBlOS file with the 
supplied CPMLDR flle. 


4) Use the COPYSYS utility to put CPMLDR on the system tracks - 


of a dlSk. 


5) Test and debug your customized version of CP/M 3. 
- 


If you have banked memory, Digital Research hehornends that You 


first use your customized BIOS to create a nonbanked version of the 
zgr; ;~p;~~9h~:."t:";or;p."g~.","8;~,"Y' 
,Y,";; 
;;;g"pz"$":,"y; - 


nonbanked version of CP/M 3 before you create a banked vernlon. 


1.9 
~niriai m a d (cold ~oot) 
of CP/M 3 
- 


r;;er. 
=he Cold ~ o o t b o a d e 


- 
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1n the second stage, the cold B w t Loader loads the memory 


image of the CP/n 3 system loader program, CPMLDR, from the system 
tracks of a disk into memory and passes control t o it. sor a banked 
system, the Cold Boot ~ o a d e r loads CPMLDR into Bank 0. 
A PROM 


loader can perform stages one and rw. 


In the third atame. CPMLDR reads the CPW3.SYS file. which 


contains the BOOS and o6stonired BIOS, from the the data are; of ;he 
disk into the memory addresses assigned by GBNCPM. 
In a banked 


System, CPnLDR reada the oomon part of the eoos and 610s into the 
colnmon Dart of memorv. and reads the banked art of the BOOS and 
610s inlo the area oi'rnemory below 
bas'e in e k k o.--c;Goi 


then transfers control to the Cold B 
e 
system lnitializarion 


routine in the 610s. 
- 
For the final stage, the B ~ O S 
Cold Boer routine, BIDS Function 


0, performs any remaining necessary hardware initialization. 
displays the sign-on message, and reada the CCP from the system 
tracks or from a CCP.COM file on disk into location lOOA of the TPR. 
- 
The Cold B W T routine transfers control to the CCP, which then 
displays the system prmpt. 


Section 2 provides an overview of the organization of the 
- 
system control nlock and the data structures and functions in the 
CP/M 3 BIOS. 


- 


~ n d 
of Section 1 


Section 2 


CP/M 3 BlOS Overview 


This section describes the organization of the CP/M 3 610s and 
the BIOS jump vector. It provides an overview of the system Control 
BloCk, followed by a disc"8eiO"of system initialization pPPCCdYYee, 
character I/O, clock support, disk I/O, and memory selects and 
moves. 


2.1 
organization of m e BXOS 


=he BIOS is the CP/M 3 module that contains all hardware- 


dependent input and output routines. TO configure CP/M 3 for a 
particular hardware environment, use the sample BIOS supplied with 
t h ~ s 
document and adapt it to the specific hardware of the target 
system. 


Alkernatlvely, you can modify an existing CP/M 2.2 BIOS to 
install CP/M 3 on your target machine. Note that an unmodified CP/M 
2.2 s ~ o s 
does not work vith the CP/M 3 operating system. 
see 


~ppendix C for a description of the lnod~ficatlons necessary to 
convert a CP/M 2.2 BTOS to a CP/M 3 6105. 


=he B ~ O S 
is a set of routines that performs system 
initialization, characrer-oriented I/O to the console and printer 
devices, and physical sector I/O to the disk devices. The BIOS also 
contams routines that manage block moves and memory selects for 
systems vith hank-rultched memory. The BIOS supplies tables that 
d e f ~ n e 
the layout of the disk devices and allocate buffer space 
which the B W S uses to perform record blocklng and deblooking. The 
BIOS can maintain the system time and date in the System Control 
Block. 


Table 2-1 describes the entry points into the BIOS from *he 


Cold Start Loader and the 8005. 
Entry to the BIOS Is through a lump 


vector. me jump vector is a set of 33 jump instructions that pass 
program control to the individual BIOS subroutines. 


YOU must include all of the entry points in the 810s jump 


vector In yovr BIOS. Hovever, If yovr system does not support some 
of the functions prov~ded for in the BIOS, you can use empty 
subcout~nes for those funct~ons. For example, if your system does 
nor support a printer, JMP LIST can reference a subroutine 
coneistinq of onlv a RBT instruction. able 2-1 shows the elements 
of the junp vector. 
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rable 2-1. 
CP/* 3 BIOS ~ v r p 
vector 


~ a c h 
jump address in able 2-1 corresponds to a particular 
subroutine that performs a specific system operation. Note that two 
entry points are reserved for future vers~ons 
of CP/M, and one entry 
point is provided for OEM subrout~nea, accessed only by direct 810s - 
calls using e m s Function 50. able 2-2 shows the five categories 
of system operations and the function calls that accomplish these 
operations. 


- 


NO. Instruction 
Description 


0 JMP BM)T 
Perform cold start initialization 
1 JMP WBOOT 
Perform warm start initialization 
2 JMP CONST 
Check for console input character ready 
3 JMP CONIN 
Read Console Character in 
4 JMP CONOUT 
Wrlte Console Character out 
5 JMP LIST 
Write List Character out 


6 
JMP ~ " L U X O ~ 
write ~uxiliary output Charaotel- 


7 JMP AUXIN 
Read huxlliary Input Character 


8 
JMP HOME 
Hove to Track 00 on Selected Disk 


9 JMP SELDSK 
Select Disk Drive 
10 JMP SETTRK 
Set Track Number 


11 JMP SETSEC 
Set Sector Number 
12 JMP SETDMA 
Set DLU Xddress 


13 JHP READ 
Read Specified Sector 
14 JHP WRITE 
Write Specified Sector 
15 JMP LISTST 
Retvrn Llst Status 
16 JHP SECTRN 
Translate Logical to Physical Sector 
17 JHP CONOST 
Return Output Status of Console 


18 JHP AUXTST 
Return Input Status Of AYX. Port 


19 JMP AUXOST 
Return Ourput Status Of AYX. Port 


20 JMP DEVTBL 
Return address of Char. 1/0 Table 
21 JMP DEVINI 
Initialize Char. I/O Devices 
22 JMP DRYTBL 
&turn ~ d d r e s s 
of ~ i s k 
Drive Table 
23 JMP MULTIO 
Set Number of Logically Consecutive 
sectors to be read or written 


24 JMP PLUSA 
rorce physical ~ v f f e r Flushing for 
user-supported deblocking 


25 JIIP MOVE 
Melnory to Memory Move 
26 JMP TIME 
Tine Set/Get signal 
27 JMP SELMEU 
Select ~ a n k 
of Memory 
28 JHP SETBNR 
specify ~ a n k for DLU operation 
29 JMP XMOVE 
Set Bank When a Buffer is in a Bank 
other than 0 or 1 
30 JHP U S B ~ ~eserved for system Implementor 
31 JMP RESERY~ ~ e ~ e r v e d 
for ~ u t u r e 
Use 
32 JHP RESERVZ 
Reserved for Future Use 


- 
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Table 2-2. 
CP/n 3 810s Iunctions 


I 
operation 
~unotion 
I 


1 
system I"iti.li..tiI" 


B W T . W B W T . DEVTBL. DEVINI, DRVTBL 


Character I/O 


CONST, CONIN, CONOUT, LIST, AUXOUT, AUXIN, 
LISTST, CONOST, AUXIST, AUXOST 


Disk I/O 


HOME, SELDSK, SETTRR. SETSBC, SETDUA, 
=AD, 
WRITB, SBCTRN, MULTIO, FLUSH 


nemory selects and Moves 


MOVE, SELIIEM, SETBNR, XMOVE 


Clock Support 


YOU do not need to implement every function in the BIOS jump 
- 
vector. However, to operate. the 8005 needs the B O M , W B O M , CONST, 
CONIN, CONOUT, EOME. SELDSR, SETTRR. SETSEC. SETDYA, READ, WRITE, 
SECTRN, MULTIO, and PLUSH subroutines. Ilnplelnent SELHEH and SETBNR 
only in a banked environment. 
You can implement MULTIO, FLUSH, and 


TlllE as ceturns sith a zero in register I. DEVICE and some other 
- 
utilities use the reaain~ng 
entry points, but it is not necessary to 
fully implement them in order t o debug and develop the system. 


note: include all routines but make the nonimplelaented routines a 
- 
RET instruction. 


2.2 
System Control Block 
me system control ~ 
i 
~ 
~ 
k 
(SCB) is a data structure located in 


the BDOS. The SCB is a comunicationa area referenced by the B W S , 
the CCP, the BIOS, and other system components. The SCB contains 
system parameters and variables, some of which the BlOS can 
reference. 
The fields of the SCB are named, and definitions of 
these names are supplied as public variable and subroutine namee in 
the SCB.ASM file contained on the distribution disk. 
See Section 
3.1 for a discussion of the System control lock. 


CP/M 3 System Gulde 
2.3 
System Initialization - 


2.3 
s y s t a Initialization 


m e n the BWT and YBOOT routines of the eros get control, they - 


must inieiaiize two system parameters in page zero of memory, as 
shown in Table 2-3. 


5.6.7 
Set to JnP BOOS, the primary entry point to 
CP/M 3 for transient program.. 
The current 


address of the BDOS is maintained in the 
variable @MXTPA in the System Control Block. 
(see Section 3.1. "system control slook," and 


- 


Table 2-3. 
Initialization of Page zero 


I 
eIos Function 1: W C ~ T on page 52.1 
I 


The BOOT and WSWT routine must load the CCP into the TPll in 


~ a n k 
1 at location 0100H. 
he CCP can be loaded in two ways. 
If 
there is sufficient space on the sysrem tracks, the CCP can be 
stored on the system tracks and loaded from there. If you prefer, 
or if there is not sufficient space on the system tracks, the BIOS 
Cold BOOT routine can read the CCP into memory from the file CCP.COM 
on disk. 


- 


Location 


If the CCP is in a .con file, use the BOOT and Y g W T routines 


to perform any necessary system ~nitialization, then use the Boos 
functions U) OPEN and RElD the Cr2P.COM file lnto the TPh. In bank- 


Description 


axrtched systems, the CCP must be read lnto the TPA in Bank 1. 


0.1.2 
set to JMP WBWT (OOOOR: JMP 810S+31. Location 
1 and 2 must contain the address of YgWT ~n 
the jump vector. 


~n bank-switched svstems. "our cold BOOT routine can -lace a 


COPY of =he CCP into a-reserve$ area of an alternate bani after 
loading the CCP into the T P ~ 
in ~ a n k 
1. 
Then the Warm BOOT routine 
can copy the CCP into the TPA in ~ a n k 
1 from the alternate bank, 
rather than reloading the CCP from disk, thus avoiding all disk 
accesses during warm starts. 


=here is a 128-hvke buffer in the resident oortion of the ~ w s 


in a banked system that can be used by BOOT and ~ O O T . The address 
of thls buffer is stored in the SCB variable BBNKBF. BOOT and WBOOT 
can use this buffer when coovina the CCP to and from the alternate 
bank. 
.. 
> 


The system tracks for CP/M 3 are usually partitioned as shorn 
in the follovlng figure: 
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Figure 2-1. 
C P / ~ 3 system Tracks 


~ h e c o l d 
start procedure is designed so you need to initialize 
the system tracks only once. *his is possible because the system 
traoks contain the system loader and need not change when you change 
the CP/M 3 operating system. 
he cold start ~ o a d e r loads CPMLDR 


into a constant memory location that is chosen when the system IS 
configu~ed. nowever 
CPMLDR loads the BDOS and BIOS system 


ccaoponents into memory is specified in the CPM3.SYS file generated 
by GBNCPM the system generation utility. Thus. CP/M 3 allows the 
user to c&flgure 
a new system with GENCPH and then run it without 
having to update the system tracks of the system disk. 


2.4 
Character I/O 


CP/M 3 assumes that all simple character 1/0 operations are 


performed in (-bit ASCII, upper- and loweroase, with no parity. An 
ASCII CRTL-Z (1AH) denotes an end-of-file condition for an input 
device. 


Table 2-4 lists the characteristics of the logical devices. 


able 2-4. 
CP/* 3 m i c a 1 erri ice Characteristics 


~ L Y ~ C L I 
Characteristios 
1 


CONIN, CONOUT 
C he 
i n t e r a c t i v e o o n s o l e t h a t 
communicates with the operator, 
accessed by CONST. CONIN, CONOUT, and 
CONOUTST. Typically, the CONSOLE is a 
device such as a CRT or teletype, 
interfaced serially, but it oan also 
be a memory-mapped video display and 
keyboard. The console is an input 
device and an output device. 


LIST 
he syatem printer, if it exists on 
your system. LIST in usually a hard- 
copy device such as a printer or 
teletypewriter. 


RUXOUT 
he auxiliary character output device, 
such as a modem. 


AUXIN 
The auxiliary character input device, 
such as a modem. 
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Nore that you can define a aingle peripheral as the LIST. 
AUXOUT, and AUXIN device simultaneously. 
If you assign no 
peripheral device as the LIST, AUXOUT, or AUXIN device, the AUXOUT 
and LIST routines can just return, and the AUXIN routine can return 
with a 1AB ICTRL-Zl in register A to indicate an immediate end-of- 
file. 


CP/n 3 supports characte~ device I/O redirection. This means 
that you can direot a logical device, such as CONIN or AUXOUT, to 
one or more physical devices. 
The DEVICE utility allows you to 
reassign devices and display, and to change the current device 
configurations, as described in the CP/M Plus User's Guide. The 1/0 
redirection facility is optional. YO" shovld not implement it ""Cil 
the rest of your BlOS is fully functional. 


1.5 
Disk I/O 


The BDOS accomplishes disk 1/0 by making a sequence of calls to 
the various disk access subroutines in the ~ 1 0 s . The subroutines 
set up the disk nvmher to access, the track end aector on a 
particular disk, end the ~ i r e c t 
~ e m o r y 
Access ( D m ) address and bank 
involved ~n the I/O operation. 
~ f t e r these parameters are 
established, the BDOS calls the Reao or WRITE function to perform 
the actual 110 operation. 


~ o t e 
that the BOOS can make a single call to SELDSK eo select a 
disk drive, follow it uikh a nunber of read or v r i ~ e 
operations to 
the selected disk, and then select another drive for subsequent 
operations. 


CP/M 3 supports multiple sector read or write operations to 


optimize roeatlonal latency on black disk transfers. 
You can 
implement the multiple sector T/O facility in the BIOS by using the 
multiSeCtOT count passed to the NVLTIO entry point. The BDOS calls 
~ 
T 
I 
O 
to read or write up to 128 sectors. or every seotor nunber 


1 to n, the BWS calla S E T D ~ 
then calls READ or URITE. 


Table 2-5 shows the sequence of BIOS calls that the B W S makes 


to read or write a physical disk sector in a nonbanked and a banked 
system. =able 2-6 shows the sequence of calls the BOOS makes to the 
BIOS to read or write multiple canriguoue physical sectors in a 
"Onbanked and banked system. 
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Table 2-5. 
llDMl C a l l s to 81- 
i n IIOnbankcd a d Banked S7ste.s 


C a l l e d for every read or write of a 
physical sector. 


Nonbanked B W S 


C a l l e d for every read or r r i t e of a 
physical sector. 


C a l l 


SETDlUL 
C a l l e d for every read or write of a 
physical sector. 


READ, WRITE 
C a l l e d for e v e r y read or write of a 
physical sector. 


EIplanFltion 


Banked BWS 


SELDSK 
C a l l e d o n l y when d i s k i s i n i t i a l l y 
selected or reselected. 


SELDSK 
C a l l e d o n l y when d i s k i s i n i t i a l l y 
selected or reselected. 


SETTRK 
C a l l e d for e v e r y read or w r i t e of a 
physical sector. 


SETSEC 
C a l l e d for e v e r y read or write of a 
physical sector. 


C a l l e d for e v e r y read or write of a 
physical sector. 
I 


( 
sETB~JK 
C a l l e d for every read or write of a 
physical sector. 


I 
mm, m I m 
c a l l e d for e v e r y read or r r i r e of a 
physical sector. 
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rable 2-6. 
multiple sector I/O in nonbanked and Banked systems 


f 
Nonhanked BDOS 
I 


I 


SELDSK 
Called only when disk is initially 
selected or reselected. 


MULTIO 
Called to inform the BIOS that the next n 
call* to disk READ or disk WRITE require a 
transfer of n contiauous oh~sioal 
sectors 


to ~OntiguouS ..m;y. 
- - 


SETTRK 
Called for every read or write of a 
physical sector. 


SETSEC 
called for every read or write of a 
physical sector. 


SETDHA 
celled for every read or write of a 
phy~ical sector. 


READ, WRITE 
Called for every read or vrite of a 
ohvsical sector. 


Banked BDOS 


SELDSX 
called only when disk is initially 
selected or reselected. 


M u ~ T l o 
Called eo inform the 610s that the n e x t n 
calls to disk READ or disk WRITE require a 
tranafer of n contiguous physical sectors 
to contiguous memory. 


SETTRK 
Called for every read or write of a 
physical sector. 


SETSBC 
called for every read or write of a 
physical sector. 


SETDHA 
Called for every read or write of a 
physical sector. 


SETBNK 
called for every read or write of a 
physical rector. 


REID, WRITB 
Called for every read or write of a 
physical sector. 
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Table 2-7 
showa the sequence of Boos calls to read two 


CODtigu0~8 physical sectors in a banked system. 


Table 2-7. 
Reading Two Contiguous sectors in Banked System 


Call 
I 
Exolanation 
I 


SELDSR 
MULTIO 


called to initially select disk 


SETTRK 
with a value of 2 


SETSEC 


For first sector 
~ O I 
first rector 


SETDMA 
SETBNR 


For flrsr sector 


SETTRR 
or second sector 
SETSEC 
SETOrn 


For second secror 


SETBNK 


For second Sector 


The CP/M 3 B W S performs ~ t s 
own blocking and dehlocklng of 


lwical 128-byte records. u ~ l i k e 
earlier versions of CP/M, the BTOS 


READ and WRITE routines always transfer physical sectors as 
specified in the Disk parameter Block to or fro. 
the D m buffer. 


he Disk ~arameter ~ e a d e r defines one or more physical secror 
buffers which the BOOS uses for logical record blocking and 
deblocking. 


In a banked environment, CP/M 3 maintains a cache of deblocking 


buffers and directory records using a Least Recently used (LRU) 
buffering scheme. =he LRU buffer is the first t o be reused when the 
system runs out of buffer space. The BOOS maintains separate buffer 
pools €0. dirertory and data record cachlng. 


The BIOS contains the data structures to control the data and 
directory buffers and the hash tables. You can either assign these 
buffers and tables yourself in the BIOS, or allow the GENCPM utility 
to generate them automatically. 


Rash tables greatly speed directory searching. 
The B W S can 


use hash tables to determine the location of directory entries and 
therefore reduce the number of disk accesses required to read a 
dlrectorv entry. =he hash table allows the BOOS to directlv access 
the aector of ihe directory containing the desired directo;~ 
without having to read the directory sequentially. BY elim~nating a 
sequential readof the directory records. hashin4 also increases the 
percentaqe of tine that the den~red 
dliecrory record rs lo a b~ffcr. 


e:lnlnarlng 
rhe need £0. any physical drsr acce-sea zn these cases. 


Haan tanles and d~reccory sacnes ellnlnate many of t h e d~rectory 
dCCeSSF8 CFaYLred When accPPsln0 lacue f l . r h . 
However. I n a 


nonhanked syieem, hash tables inciease-the size of the opdrating 
system. 
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when the B ~ O S 
finds an error condition, the READ and WRITE 
routines ehould perform several retries before reporting the error 
condit~on to the BOOS. 
en retries are typical. 
If the BIOS 
returns an error condition to the BOOS, the BWS 
reports the error 
to the user in the following form: 


CP/M ~ r r o r 
on d: oisk r/o 


he d: represents the drive apecificarion of the relevant drive. 


TO provide better diagnostic capabilities for the user, it is 


~ 
~ 
~ 
~ 
I 
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~ 
~ 
~ 
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BOOS. =he BIOS should interrogate the SCB ~ r r o r 
Mode Variable to 
determine if it is appropriate to print a message on the console. 


2.6 
-ry 
Selects and *oees 


.our BIOS functions are provided to perform memory management. 
The functions are MOVE 
X M V E , SBLUEM, and SETBNK. 
The XMOVE, 


SELMW, and SETBNR 
management routines are applicable to the 
BIOS Of banked systems. 


=he BWS uses he BIOS MOVE routine to perform nemory-to-memory 


block transfers. 
I" a banked system, the BDOS calls XMOVE to 


specify the source and destinaCion banks to he used by the MOVE 
routine. If you use melnory that is not in the common area for data 
record buffers, you muat lmplenent the m o m routine. 


=he BWS 
vees SEWIBM when the operating syetem needs to execute 


code or access data in other than the currently selected bank. 


he BWS calls the SETBNK routine prior to calling disk 
or 
disk WRITE functions. 
The SETBNK routine Rust save its specified 
hank as khe om hank. when the BWS invokes a disk 1/0 routine, the 
I/O routine should save the current hank number and select the urn 
hank prior to the disk READ or WRITE. After completion of the disk 
m o or WRITE the disk r/o routine must reselect the current bank. 
~ o t e 
that vh& 
the BOOS calla the disk T/O routines, ~ a n k 
D is in 
context (selected). 


2.7 
Clock SuppOrt 


15 the system has a real-tine closk or is capable of keeping 


yt;*k;y;;;;Yc;; 
;:;;;;:; ;;y;ztzffy; 
;"~;;:t;;;:;i:~:;;k'~ 


lock and update the rime on =lock ~nterrupts. 610s runction 26 is 
provided for those systems where the clock is unable to generate an 
Interrupt. 


- 
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- 
The tine of day is kept as four fields. @DATE is a binary word 
containing the number of days since 31 December 1977. 
=he bytes 


@AOUR, @*IN, and @SEC in the System Control Black contain the hour. 
minute, and second in Binary Coded Decimal (BCDI format. 
- 
End of section 2 


- 


- 
Section 3 
CP/M 3 BIOS Functional Specifications 


This section oontains a detalled description of the CP/M 3 
BIOS. 
The section fzrst discusses the sros data seructures and 


theic relationships, including the System Control Block the drxve 
table, the Disk Parameter Header, the ~ i s k 
Parameter block, the 


Buffer Control Blocka, and the charaoter I/O table. The overv~ew 
of 
the data structures is followed by a summary of the functions I" the 
BIOS jump vector. 
A detalled description of the entry values and 
returned values for each jump instruction in the BIOS lump vector 
follows the summary. 
The last part of this section discusses the 


Steps to follow vhen assembling and linking your customized BIOS. 


- 


The Sys$ea Control Block ISCBI is a data structure located in 
. ..~- 


DRlare the vallable names you want to reference ~n the SCB as 
- 
externals in your BIOS.ASM source flle. Then link your EIOS vlrh 
the SCB.REL nadule. 


add,e:k~,'.S;,"i;,"~df;;edF;,",e 
h'gh-016" 
byte of the various SCB 


The llnker marks absolute external 
equates as page relocatable vhen generating a System page 
Relmatable ISPRI format file. GENCPM recognizes page relocatable 
addresees of OFExxH as references to the System Control Block ~n the 
BDOS. GENCPM changes these addresses to p o ~ n t to the actual SCB in 
the BDOS when it IS relocating the system. 


Do not perform erseably-time arithmet~c on any references to 
the external labels of the SCB. The result of me arlthneric could 
- 
alter the page value to something other than OFEH. 


Listing 3-1 show* the SCB.ASM flle. 
The listing ahovs the 
field names of the System Control Block. 
A 
@ 
before a name 
p2p9;';"s :E:tl:;efS,; 
:ztfn::';;ti;ni 
preceding e name indicates 
In the llstlng, r/w means 
Read-write, and r/o means Read-Only. 
The BIOS can modify a ~ 
~ 
~ 
d 
- 


~::~x;;;~~~~h' 
~,"~m~;~C~t,","~~~~~o~::~;O;~cy~na~e',.ai~~ble 
3-1 
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title asvstem control slock oefinirion for CP/M3 BIOss 


publio @civet. @covet, eaivec, eaovec, elovec, ebnkbf 
- 


public @crdma. ecrdsk, evinfo, eiesel, @fx, susrcd 
public emltio, eerade, eecdsk, @media, abflgs 
public @date, @hour, @mn, @seo, ?erjnp, @mxtpa 
- 


scb$bare eqv 
OFEOOR 
7 Base of the sce 


IMXTPA 


; ConsOle Input Redirection 
; vector (word, r/wl 
; Console Output Redirection 
; vecror (ward, r/vl 
; Auxiliary Input Redirection 
; veotor (word, r/wl 
; Auxiliary output Redirection 
; vector (word, r/wl 
; ~ i s t 
output Redirection 
; vecror (word, r/wl 
; ~ d d r e s s 
of 128 Byte Buffer 
; for sanked Blos (word, c/o) 
; Cucrent DMA Address 
; (word, r/nl 
; current Disk (byte, r/ol 
; 8005 variable 'INFO" 
; (ward, r/ol 
I FCE Flag (byte, r/01 
; BWS Function for Error 
; Messages (byte, r/ol 
; current user Coae (byte, 1/01 
; CYr.."k 
NYlriseCtor count 


; (byte,r/wl 
; a w s Error node (byte, c/o) 
; BOOS Error Disk (byte, r/ol 
; set by BIOS to indlcate 
; open door Ihyte.r/Yl 
i BDOS nessaqe Size Flag 


. 
. 


; TOP of User TPA 
: (address at 6.7) (word, r/ol 


end 


~ i a t i n g 3-1. 
SQ).Mn Pile 
- 


- 
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The follovlng table describes in detail each of the fields of 
- 
the Syaten Control Block. 


Table 3-1. 
s ~ s t e m 
Control Block Fields 


These fields are the 16 bit 1/0 redirection 
vectors for the five logical devices: 
console 


input, EOnSOle D U t D Y t , 
auxiliar" inout. 


- 


auiiliary output, and the llst device. '(see 
section 3.4.2, 
.character I/o Punotions:) 
I 


Field 
neaning 


@CIYEC, @COVEC, @AIVBC, BAOVEC, @LOVEC 
(Read-Write 
variable) 


@BNKBP 
(Read-Only Variable) 


@BNKBF contains the address of a 128 byte 
buffer in the resident portion of the BDOS in a 
banked system. 
This buffer is available for 


Use during BOOT and WBOOT only. You can use it 
to transfer a copy of the CCP from an m a g e in 
an alternate bank if the system does not 
support interbank moves. 


BCRLWA, @PX, @USRCD, @ERDSK 
(Read-Only Variable) 


These variables contain the current DM& 
address, the BOOS function number, the current 
veer oade, and the disk code of the drive on 
which the lase error oocurred. 
They can he 
displayed when a Boos error is intercepted by 
the BIOS. 
See ?ERJMP. 


@CRDSK 
(Read-Only Variable) 


@CRDSK is the current default drive, set by 
B W S P""Oti0" 
14. 


- 
- 


BVINPO. @ m S E L (Read-only Variable) 


If @RsSEL is equal to OPFA then @"INFO contains 
the address of a valid PCB. 
I£ @RESEL is not 
equal to OFPH, then @VlAPO is undefined. 
you 


can use @VINFO to display the filespec when the 
BIOS intercepts a BDOS error. 
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=able 3-1. 
(continued) 
- 


I 
Field 
Meanin. 


/ 
@MLTIO 
(Read-write Variable) 
I 


@HLTIO contains the current multisector count. 
he BIOS can change the multisector count 
directly, or through BOOS Function 44. 
The 
value of the muitisector count can range from 1 
to 128. 


@ERIIDE (Read-only Variable) 


@ERHDE contains the current BDOS error mode. 
OFFB indicates the BDOS is returning error 
codes to the application program without 
displaying any error messages. 
OFEH indicates 
the BDOS is both displaying and returning 
errors. any other value indicates the Boos is 
displaying errors without notifying the 
application program. 


@MEDIA 
(Read-write Variable1 


@HBOIA i8 global system flag indicating that a 
drive door has been opened. 
The BIOS routine 
that detects the open drive door sets this flag 
to OEFH. =he BTOS r o u t m e also sets the M E D I ~ 
byte in the ~ i s k 
Parameter Header associated 


vlth the open-door drive to OFPH. 


@BFLOS 
mead-only Varlablel 


=he BOOS in CP/II 3 produces two kinds of error 
messages: 
short error messages and extended 
error messages. 
short error messages display 
one or two l m e s of text. Long error messages 
display a third line of t e x t containing the 
filename, filetype, and Boos Function Nunbei 
involved In the error. 


In banked systems, GENCPM sets this flag in the 
system control m o c k to indicate whether the 
BIOS displays ahortor extended eeeee messages. 
your error message handler should check this 
byte in the system Control lock. If the high- 
order bit, bit 7 , 
1 s set to 0, the BDOS 


displays ahorr error messages. 
If the high- 
order bit is set to 1, the BOOS dlsplays the 
extended three-1,ne eiror messages. 
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Table 3-1. 
Icontinued) 


I 
Field 
Heanin. 
I 


FOC example, t h e BOOS displays the following 
error meaaage i f t h e 610s r e t u r n s an error f r m 
READ and the BDOS i s disolavina lona error 
messages. 
. - . . 
I 


CP/M Error on d: Disk 1/0 
BWS ~ u n o t i o n - nn 
F i l e - filename.ryp 


~n the above e r r o r message, Puncrlon nn and 
f>lename.ryp represent BWS iunctlon nlnoer and 
file apeclflcarlon ~nvolved, r e a p e c r ~ v e l y . 


@DATE (Read-Write variable) 


The numbec of days since 3 1 December 1977, 
expressed as a 16-bit unsigned integer, low 
b y t e f i r s t . 
P, real-tine clook i n t e r r u p t can 
update the @DaTE f i e l d t o indicate the current 
date. 


@HOUR, @nIN, @sE€ 
(Read-write Variable) 


These 2 - d i g i t s i n a r y c o d e d Decimal (BCD) f i e l d s 
indicate t h e current hour, minuke, and second 
i f updated by a real-time clock interrupt. 


?BUMP 
(Read-Write Code Label1 


The eDOs c a l l s the error message subroutine 
through t h i s jump instruction. 
Register C 
contains an error code as follows: 


1 
permanent Brror 


2 
Read Only Disk 


3 
Read Only F i l e 
4 
S e l e c t Error 
7 
Password BETOT 


8 
Pile E x i s t s 


9 
7 i n Filename 
- 
Error code 1 above results i n the BOOS message 
Disk I/O. 


- 
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Table 3-1. 
(continued) 
- 


B ~ ~ T P A 
contains the address of the current BDOS 


entry point. 
This is also the address of the 


top of the T P ~ . he BWT 
and wem routines of 
the BIOS must use this address to initralize 
the 800s entry JHP instruction at location 
005R, during system initialization. 
Each tine 


3.2 
character 110 Data Structures 


~ h e s l o s 
data s~rvcture 
CHRTBL in a character table describing 


your CHRTBL. 


=he mode byte specifies whether the device is an input or - 


output aevlce, *herher it has a selectable baud rate, whether it is 
a serial device, and if XON/XOFF protocol is enabled. 


CP/M 3 System ~ u i d e 
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Listing 3-2 shows a sample character device table that the 
DEVICE utility uses to set and display I/O direction. 


I sample character device table 


chrtbl db 'CRT . 
console VDT 


db nb$in$out+mb$serial+nb$soft$baud 
db baud19600 


~ ~ ' I P T 
* 
system serial printer 


db mb$output+mb$serial+mb$ooft$bbbd+mb$xon 
db baudS9600 


db ' ~ 1 8 1 0 
8 
2 alternate printer 


dh nb$OutPut+mb$serial+nb$sofr$baud 
db baudO9600 


db 'MODEM ' 
: 300 baud modem port 
db mb$inSout+mbSserial+nb$soft$baud 
db baudS300 


db 'VAX ' 
interface to V ~ X 
11/780 


db mb$in$out+nb~serial+mb$soft$babd 
db baud19600 


db 'DIABLO' 
i Diablo 630 daisy wheel printer 


db mb$autput+mhSserial+mb$soft$baud+nh$xonSxoff 
db baud$l200 


db'CBI1 
' 


db ab$outpur 
; centronics type Parallel prinrer 


db baud$none 


dh 0 
: Cable terminator 


Listing 3-2. 
S q l e Character Oerrice Table 


Listing 3-3 shows the equates far the fields contained in the 


sample character device table. "any systems do not support all of 
these baud rates. 
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Structures 


Figure 3-1 shows t h e r e l a t i o n s h i p s between the drive table, the 


~ i s k 
Parameter neader, and the Data and Directory Buffer control 


~ 1 0 c k f l e i d s and t h e i r respective d a t a structures and buffers. 


kT 
: , 9 
.dl, 


I 
D8reCtoryBuffer 
- 
- 
Data Buffer 
- 


~ i g v r e 3-1. 
~ i s k 
Data Structures in a Banked S y s t a 
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he drive table consists of 16 words containing the addresses - 


Of the Disk paramete. Headera for each lqical drive name. A through 
P, and takes the genera1 form: 
- 


drivetable dr 
dphO 


dr 
dphl 


dv 
dph2 


dw 
dphF 
- 


~f a logical drive does not exist in your system, the corresponding 
="try in the drive table must be zero. 
- 


The GENCPn utility aoceases the drive table to locate the 


varioue disk parameter data structures, so that it can determine 
~ h i c h 
system configuration to use 
and optionally allocate the 


variovs buffers itself. you nust e:pply 
a drive table if you want 


GENCPM to do this allocation. 
1f certain addresses in the Disk 


permeter waders referenced by this drive table are set to OFFFEH, 
GEUCPM allmates the appropriate data structures and uedates the 
DPR. YOU can supply the drive table even if you have performed your 
own memorv allocation. 
See the BTOS DRVTBL function described in 
section 3l4.1. 


3.3.2 
Disk Par-ter 
Beader 


~n ~ i g u r e 
3-2, which shows the format of the oiek Parameter 
Header, b refers to bits. 


pigare 3-2. 
~ i s k 
parameter Header Format 
- 


~ a b l e 
3-2 describes the fields of the Disk Parameter Header. - 


- 
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Table 3-2. 
oisk Parameter Reader Fields 
- 
I 
Pield 
1 
Comments 
1 


XLT 
Set the XLT field t o the address of the logical to 
phyaioal sector translation table. If there is no 
- I 


neotor translation and the logical and physical 
SectOz numbers are the sane, set XLT to 0000~. ~ i s k 
drives with identical aector skew factors can share 
the sane translation table. 


XLT is the valve passed to SBCTRN in regiaters DB. 
Usually the translation table consists of one byte 
per physical sector. Generally, it is advisable to 
keep the number of physical sectors per logioal 
track to a reasonable value to prevent the 
translation table from becoming too large. I" the 
case of disks with multiple heads, you can compute 
the head number from the krack address rather than 
the sector address. 


-0- 
These 72 bits (9 bytes1 of zeroes are the scratch 
area the BDOS uses to maintain various parameters 
- 
I 
associated with the drive. 


IIP is the nedia n a g . =he BWS resets HF to zero 
when the drive is logged in. The BIOS can set this 
flag and erreor~ in the sce co OaaR if it detects 
that a drive door has been opened. 
If ehe flag is 
set to OFPH, the BDOS ohecks for a media change 
prior to performing the neat BWS file operation on 
that drive. If the BOOS determines that the drive 
Contains a new volume, the BOOS perfor.. 
a login on 
that drive, and resets the HP flag to 008. 
Note 
that the B W S checks this flag only when a system 
Call is made, and not during an operation. 
Usually. this flaa is used onlv bv svatems that 
support dwr-open interrupts. . . . 


7 
- 


DPB 
Set the DPB field to the address of a Disk 
Parameter Block that describes the characreriatics 
of the disk drive. Several Disk Parameter ~ e a d e r s 
can address the same Disk ~arameter 
m o c k if their 
drive characteristics are identical. 
he ~ i s k 


Parameter Block is described in Section 3.3.3.) 


ce/M 3 system Guide 
3.3 
BIOS ~ a t a 
Structures 


able 3-2. 
Ieonttnuedl 


ALV 
ALV is t h e address of t h e scratchpad area c a l l e d 
the a l l o o a r i o n vector 
which t h e BDOS uses to keep 


d i s k storage 
inforaaeion. 
T h i s area 


must be unique f o r each drive. 


=he e l l o c a t i o n 
" s ~ a l l y r e q u i r e s 2 h i t s for 
e a c h block on t h e d r i v e 
~ h u s . 1engChIALVl 
= 
(osn/4) + 2. 
( s e e ~ a u e 
313 f o r an explanation of 


the OSM f i e l d . ) 
1n the nonbanked v e r s i o n of CP/M 


- 
- 
- 


t h e d r i v e . 
I n t h i s case, length(ALV1 = (DSH/8l + 


- 
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Table 3-2. 
(continuedl 


m e l d 
c m e n t s 


lit" 
allocation vectors, the uaer must type a CTRL-c at 
(continued) the system prompt to reset the disk system to ensure 


aoourate reporting of free space. 
Set ALV to 


OPPFBH for GENCPM to automatically assign space 
for the allocation vector, single- or douhle-hit, 
during system generation. I" the nonbanked system, 
GENCPM prompts for the type of allocation vector. 
~n the banked syscem, the allocation veotor is 
always double-hit and can reside in cornon memory 
or ~ a n k 
0. when GENCPM automatioally assigns space 
for the allacatian vector (ALV = OPPFEHI, it places 
the allocation vector in Bank 0. 


DIRBCB 
set D ~ R B C B to the address of a single directory 
Buffer Control Block (BCBI in an unbanked system. 
Set DIRBCB to the address of a BCB list head in a 
banked system. 


Set DIRBCB to OPPPER for GENCPM to set up the 
D I ~ B 
field. he BWS uses directory buffers for 
all accesses of the disk directory. 
Several D P H ~ 


can refer to the same direotory BCB or BCB list 
head, or, each DPH can reference an independent BCB 
or BCB list head. 
Section 3.3.4 
describes the 
format of the Buffer Control lock. 


DTABCB 
Set DTABCB to the address of a single data BCB in 
an unhanked system. Set DTABCB ko the address of a 
data BCB list head in a banked system. 


See DTI\BCB to OPPFEE for GENCPM to set up the 
DTLBCB field. The BDOS uses data buffers to hold 
physical ~eotocs so that it can block and deblock 
logical 128-byte records. 1f the physical record 
size of the media associated with a DPH is 128 
bytes, you can set the DTABCB field of the DPH to 
OFFWR, because in this case, the BDOS does not use 
a data buffer. 


RASH 
mm oontains the address of the optional directory 
hashing table associated with a DPH. 
Set HISR to 


OFFFFH to disable directory hashing. 
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Table 3-2. 
(continued) 


I 
Field 
/ 
comments 
I 


bytes far each directory entry of the disk. 


KBANK 
set EBANK to the bank number of the hash table. 
HBIUIK is not used in unbanked systems and should be 
set to zero. The hash tables can be contained in 
the system bank, cononon memory, or any alternate 
bank except Bank 1, because hash tables cannot be 
located in the Transient Program Area. 
GBNCPU 


automatically sets RBANK when RASR Is set to 


3.3.3 
~ i s k 
Parameter ~1-k 


ligure 3-3 shows the format of the uisk Parameter Block, where 
b refers to bits. 


Table 3-3 describes the fields of the ~1.k 
parameter nlack. 


of B S H is determined by the data block 
allocation size. 


mble 3-3. 
~ i s k 
par-ter 
Block rimlds 


I 
B W ~ 


m o c k mask. 
=he value of BL" is determined by I 


the data block allocation size. 


Field 
C m e n t s 


SPT 
Set SPT to the total number of 128-byte logical 
records per track. 


- 
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Table 3-3. 
(continued) 


Extent mask determined by the data block 
allocation size and the number of diak blocks. 


Determines the total storage oapacity of the 
disk drive. 
DSM is one less than the total 


number of blocks on the drive. 


m t a l number of directory entries minus one that 
can be stored on this drive. 
The direotory 


requires 32 bytes per entry. 


ALO. A L ~ 
Determine reserved directory blocks. SeeFigure 
3-4 for nnre infomation. 


CKS 
The size o f the directory check vector, 
( O W 4 ) t l . Set bit 15 of CKB t o 1 if the drive 
is Lernanentlv mounted. 
set CKS to 80008 to 
indicate that-the drive is permanently nounted 
and directory checksumming 1s not required. 


note: 
full directory checksumming is required 
on removable lnedla to support the automatic 
login feature of CP/M 3. 


OFF 
The number of reserved tracks at the beginning 
of the logical disk. OFF 1. 
the track on which 


the directory starts. 


PSR 
Specifies the physical reoord shift factor. 


PRIl 
Speoifie~ the physical record aaek. 


- 
CP/M allocates disk space in a unit called a block. Blocks are 
also called allocation units, or clusters. 
BLS is the number of 
bytes in a block. he block size can be 1024, 2048. 4096, 8192. or 
16384 (decimal) bytes. 
- 
A large block sire decreases the size of the allocation vectors 


but can result in wasted disk space. A smaller block sire increases 
the size of the allocation vectors because there are more blocks on 
the same size disk. 
- 


There is a ceatristion on the block size. If the block size is 
1024, there oannot be nore than 255 blocks present on a loglcal 
drive. 
I n other words, if the diak is larger than 256K, ~t is 
necessary to use at least 2048 byte blocks. 
- 


=be value of BLS is not a field in the ~ i s k 
Parameter lock; 


rather, it is derived from the values of BSR and ELM as given in 
Table 3-4. 
- 
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Table 3-4. 
BSB and B U Values 


BLS 
BSB 
ELM 


The h l a k mask, BLM, equals one less than 
records in an allocation unit, (BLs/128 - 
the 
11. 


number of 128- 
or (2"BSR)-1. 


he value of the ~ l a o k 
shift ~aotor. 
BSR, is determined by the 
data block allocation size. The Block Shift Factor (BSRI equals the 
logarithm base two of the block size in 128-byte records, or 
UG2(BLS/1281. where LOGZ represents the binary logarithm funotion. 


The value of EXH depends upon M t h the BLS and whether the DSM 


v.1~. 
is less than 256 or greater than 155, as shown in Table 3-5. 


Table 3-5. 
m 
x 
i 
. 
" 
. 
E m Valves 


BLS 
I 
EXH value^ 
I 


1.024 
2,048 
4,096 
8,192 
16,384 
15 


he value of EXM is one less than the maximum number of 16K 


ertenta per PCB. 


Set EX* 
to zero if you want media compatibility with an 
extended CP/M 1.4 syacem. This only applies to double-density CP/M 
1.4 
systems, vith disk sizes greater than 2561 bytes. 
It is 
preferable to copy double-density 1.4 disks to single-density, then 
reformat then and recreate them vith the CP/M 3 system, because CP/M 
3 uses directory entries nore effectively than CP/M 1.4. 


Dsn is one less than the total number of blocks an the drive. 


osn must be less than or equal to IPPPX. 
1f the disk uses 1024 byte 


blccks (858-3. ELM-71. osn must be less than or equal to ~OPIH. The 
product B L S * ( D ~ M + ~ ) 
is the total number of bytes the drrve holds and 


must be within the capaoiey of the physical disk. 
It does not 
include the reserved operating system rracka. 


- 
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The DRM e n t r y is one l e s s than t h e t o t a l number of 32-byte 
- 
directory e n t r i e s , and is a 16-bit value. 
DRH must be l e a s t h a n or 
e q u a l t o lsLs/32 + 1 6 ) - 1. o m determines t h e v a l u e s of 110 and 
m1. me two f i e l d s ALO and A L ~ 
can t q e t h e r be considered a s t r i n g 
O f 16 b i t e , as shown i n F i g u r e 3-4. 
- 


- 
F i g u r e 3-4. 
ALO and -1 


- 
P o s i t i o n 00 corresponds ko t h e high-order 
b i t o f t h e b y t e 
labeled ALO, and p o s i t i o n 15 corresponds to t h e low-order b i t o f t h e 
b y t e l a b e l e d A L ~ . ~ a c h 
b i t p o s i t i o n reserves a d a t a block f o r a 
number o f d i r e c t o r y e n t r i e s , t h u s allowing a maximum o f 16 d a t a 
- 
b l o c k s t o be assigned f o r d i r e c t o r y e n t r i e s . 
s i t s are assigned 


s t a r t i n g a t 00 and f i l l e d t o t h e r i g h t u n t i l p o s i t i o n 15. 
ALO and 


A L ~ 
o v e r l a y t h e f i r s t two b y t e s of t h e allocation v e c t o r for t h e 
a s s o c i a t e d d r i v e . 
able 3-6 
shows DRM maxinulns f o r t h e v a r i o u s 
- 


block s i r e s . 


Table 3-6. 
BLS and Number of D i r e c t o r y Entries 


7 


* reserved b l o c k s 
2.048 
64 
reserved blocks 
1.023 
- 


4,096 
128 * reserved b l o c k s 
2,047 
8,192 
256 ' reserved blocks 
4,095 
16,384 
512 ' reserved blocks 
8,191 


- 
I€ DRM - 127 1128 d i r e c t o r y e n t r i e s ) , and BLS - 1024, t h e r e are 
32 d i r e c t o r y e n t r i e s per block, r e q u i r i n g 4 reserved blocks. 
~n 


t h i s case, t h e 4 high-order 
b i t s of %LO a r e set, r e s u l t i n g i n t h e 


v a l u e s ALO - OPOH and a L l = OOH. 
The maximum d i r e c t o r y a l l o c a t i o n 


i s 16 blocks where t h e block s i z e i s determined by BSH and BLH. 


. 
.. . . 
. . . 
. 
. 
. . 
- - 


a t t h e beginning ol 
mechanism f o r akiooil 


- 


The OPP f i e l d determines t h e number o f t r a c k s t h a t are skipped 


f t h e p h y s i c a l d i s k . 
1t can be vsed as a 
.. lg reaerved o p e r a t i n g system t r a c k s , which on 


system d i r k s c o n t a i n t h e c o l d m o t Loader. CPMLDR, and p o s s i b l y t h e 
- 
CCP. 
1t is a l s o used t o p a r t i t i o n a l a r g e d i s k i n t o smaller 


segmented s e c t i o n s . 
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PSH and PEW determine the physical sector sire of the disk. 


~ 1 1 
disk I/O 
is in eerns of the physical sector sire. Set PSH and 


~511 to zero if the sros is blocking and deblocking instead of the 
BDOS. 


PSH specifies the physical record shift factor, ranging from 0 


to 5, correeponding to physical record sizes of 128, 256, 512, 11, 
2K 
or 4K bytes. 
It is equal to the logarithm base two of the 


ph;sical 
record size divided by 128, or ~ ~ i 2 1 s e c t o r _ s i z e / l 2 ~ . 
see 


Table 3-7 for PSH Values. 


PBM specifies the physical record mask, ranging from 0 to 31. 


corresponding to physical record sires of 128, 256, 512. 11. 2K, or 
1 
. 
kvtea. 
It is eoual to one less than the sector aiae divided by 
. . . . 
A 
. . . 
. - - - ~. - 


128, or, (aector_sire/l28)-1. 
see =able 3-7 for PBM valuer. 


a Buffer Control Block (BCBI locates physical record buffers 
for the BWS. 
he BDOS uses the BCB to manage the physical record 
buffers during processing. nore than one Disk Parameter Header can 
s ~ e c i f y the sane BCB. 
=he GENCPM utility can create the Buffer 


able 3-7. 
PSH and PB* values 


mre that the BINR and LINK fields of the suffer control lock 


are oresent onlv in the banked avstem. 
Therefore, the Buffer 


DRV 
REC* 
WFLG 
00 
TRACK 
SECTOR 
BUFFAD 
BANK 
LINK 


8b 
24i) 
8b 
8b 
1Bb 
1Bb 
161 
8Q 
16b 


PAM 
Sector 


eize 


~ i g u r e 
3-5. 
~ u i f e r 
control ~1-k m r m a t 


PSH 


- 
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T a b l e 3-8 d e s c r i b e s t h e f i e l d s of e a c h B u f f e r C o n t r o l Block. 
- 


T a b l e 3-8. 
B u f f e r Control Block F i e l d s 


T h e BDOS d i s r l n g u i s h e s between two k l n d s o f b u f f e r s : 
d a r e 


b u f f e r s r e f e r e n c e d by DTABCB, a n d d i r e c t o r y b u f f e r s r e f e r e n c e d by 
DIPBCB. 
In a banked system, t h e DlRBCB a n d DTABCB f i e l d s o f s Dlrk 


Parameter Header e a c h contain t h e a d d r e s s o f a BCB list head r a t h e r 
t h a n t h e a d d r e s s o f an a c t u a l BCB. 
A BCB list head is a word 


c o n t a i n i n g t h e a d d r e s s o f t h e f l r s r BCB 
~n a l ~ n k e d l i s t . 
~f 


s e v e r a l DPHr r e f e r e n c e t h e same BCB list, t h e y must r e f e r e n c e t h e 
same BCB l l a t head. 
Each BCB h a s a LINX field t h a t c o n t a i n s e h e 


a d d r e s s of t h e next BCB i n t h e l i s t , or zero I f It IS the l a s t BCB. 


F i e l d 
comment 


DRV 
I d e n t i f i e s t h e d i s k d r i v e a s s o c i a t e d w i t h t h e 
r e c o r d c o n t a i n e d i n t h e b u f f e r 
l o c a t e d at 


a d d r e s s BuFFrD. 
I f you d o not use GENCPM to 


a l l o c a t e b u f f e r r , you must set t h e OR" f i e l d t o 
OBFA. 


RECl 
I d e n t i f i e s t h e r e c o r d p o s i t i o n of t h e c u r r e n t 
c o n t e n t s o f t h e b u f f e r l o c a t e d a t a d d r e s s 
BUFPAD. 
met c o n s i s t s of t h e a b s o l u t e s e c t o r 


n m b a r o f t h e r e c o r d where t h e f l r s r r e c o r d o f 
t h e d i r e c t o r y i s zero. 


WLO 
S e t by t h e BDOS t o OFPR t o i n d i c a t e t h a t t h e 
b u f f e r c o n t a i n s new d a t a t h a t h a s n o t y e t been 
w r i t t e n to d i s k . 
when t h e d a t a i s w r i t t e n , t h e 


BDOS sets t h e WLG 
to zero t o l n d i c a t e t h e 


b u f f e r i s no l o n g e r d i r t y . 


00 
s c r a t c h b y t e used by BWS. 


TPACR 
c o n r a m s t h e p h y s i c a l t r a c k l o c a t i o n o f t h e 
contents o f t h e b u f f e r . 


SECTOR 
C o n t a i n s t h e p h y s i c a l sector l o c a t i o n o f t h e 
c o n t e n t s o f t h e b u f f e r . 


BUFPAD 
S p e c i f i e s t h e a d d r e s s of t h e b u f f e r a s s o c i a t e d 
w i t h t h i s BCB. 


BUNK 
C o n t a i n s t h e b a n k number o f 
t h e b u f f e r 
a s s o c i a t e d v l t h t h i s BCB. 
T h i s f i e l d i s o n l y 
p r e s e n t i n banked s y s t e m s . 


LINX 
C o n t a i n s t h e a d d r e s s o f t h e n e x t BCB ~n a 
l i n k e d l i s t , or zero l f t h i s is t h e l a s t BCS i n 
t h e l i n k e d l i s t . 
The LINK f i e l d is p r e s e n t 


o n l y i n banked s y s t e m s . 


CP/M 3 system ~ u i d e 
3.3 
BIOS ~ a e a 
structures - 


In banked syatema, the one-byte B m K field indicates the bank 


gB:h;;;tt;: z:;: ;:;;;;: ;;;e;;:;;;;f 
fzs 
:zt 
;:;::::;:;:;; 
- 


0, usually below the banked 8005 nodule, or I" conmon memory. The 
BANK fleld is for systems that support direct memory-to-nenory 
transfers from one bank to another. (See the BTOS XMDVE entry polnt 
in section 3.4.4.) 
- 


me BCB data structures 1" a banked system nust reside in Bank 


0 or ~n c o m n memory. 
The buffers of data BCBs can be located in 
any bank except Bank 1 (the Translent Program Area). 


For banked systems that do not support interbank block moves 


through .WOVE. the BANK fleld must be set to 0 and the data buffers 
must reside in common memory. The dlrecrory buffers can be in Bank 
0 even if the system does not support bank-to-bank moves. 


In the nonbanked system. the DPH, DIRBCB, and DTABCB can point 
to the same BCB If the DPH defines a flxed media device. 
For 


devlces vlth removable medla, the DPH DIRBCB and the DPH DTABCB must 
reference different BCBs. 
In banked systems. the OPE DIRBCB and 


DTlieCE must polnt to separate list heads. 


rn general, you can enhance the performance o f CP/M 3 by 


allmatlng more BCBs, but khe enhancement reduces the amount of TPA 
memory I" nonbanked systems. 


If you set the DPH DIRBCB or the DPH DTRBCB fields to OPPPEH, 
the OENCPM utlllty creates BCBa, allocaree physlcal record buffers, 
and set. 
these f ~ e l d s 
to the address of the BCBs. 
This allows vou 


to write device drlvers v~rhout regard to buffer requlrenents. 


3.3.5 
Data Structure Mcra Definitions 


several macro deflnltlons are rupplled with CP/M 3 to slmpllfy 


the creat~an of some of the data structures in the BIOS. 
mese 


mcros are defrned I" the llbrary file CPM3.LTB on the dlatrlbutlan 
dlSk. 


TO reference these macros in 
6108, include the follawlng 


statement: 
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Use khe DTBL macro to generate the drive table, DRVTBL. It has 


one parameter. a liat of the npas in your nyatem. 
The list is 
enclosed in angle brackets. 


=he form of the DTBL macro call is 


label: DTBL 
<DPHA,DPHB,...,DPHP> 


"here DPHA is the address of the DPB for drive A, DPHB is the 
address of the DPH for drive 8 , up to drive P. For example, 


DRVTBL: DTBL 
~ACSHDOrPDSDD.PDSD1> 


~ h i a 
example generates the drive table for a threedrive system. 


he DTBL rnaoro always generates a nixteen-word table, even if you 
aupply fewer DPH names. 
he unused entries are set to zero to 
indicate the corresponding drives do not exist. 


DPH Macro 


he DPB macro routine generates a ~ i a k 
Parameter Reader (DPHJ. 


1t requires two parameters: the address of the skew table for this 
drive, and the address of the Disk Parameter Block IDPB). 
Two 


parmeters are optional: the maximum aiae of the checkaurn veotor, 
and the maximum aize of the allocation vector. 
If you omit the 


maximum size of the checksum vector and the maximum sire of the 
allmation vector from the DPH maora invocation, the Forrespanding 
fields of the Disk Parameter Header are set to OFFPBH so that GENCPM 
aatwatioally allocates the vectors. 


he form of the DPH maore oall is 


label: DPR 
?trans,?dpb,l?csizel,l?asizel 


where: 


?trans is the address of the translation vector for this 


drive, 


Idph 
is the address of the oPa for this drive; 


?08ize is the maximum size in bytes of the checksum 
vector; 


lasize is the maximum size in bytes of the allocation 
vector. 


following example, which includea all four parameters, 


s h w s a typical DPH macro invocation for a standard single-density 
disk drive: 


PDSDO: DPH 
SKEW6,DPB$SD.16,31 
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SKEW Macza 


The SKEW macro generates a skew table and requires the 


follaring parameters: the number of physical sectors per track, the 
skew factor, and the first sector number on each traok lusually 0 or 
11. 


The form of the SKEW macro call is 


label: SKEW 
Iseos.Iskf.7fsc 


where: 


7secs is the number of physical sectors per track; 
78kf 
is the seotor skew factor; 


?fsc 
is the first sector number on each track. 


he following macro invocakion generates the eke* table for a 
standard single-density disk drive. 


SKEWS: 
SKEW 
26.6,l 


DPB Macro 


he DPB macro generates a ~ i s k 
parameter Block specifying the 


characteristioa of a drive type. 
1t requires six parameters: 
the 
physical sector siae in bytes, the number of physical sectors per 
the total number of tracks on the drive, the siae of an 


:;Sition 
unit in bytes, the number of directory entries desired, 
and the number of eyrtcn tracks to reserve at the beginning of the 
drive. There ia an optional seventh paraneter that defines the CKS 
field in the DPB. If this parameter is missing, CKS IS calculated 
from the directory entries parameter. 


=he form of the DPB macro call is 


label: DPB 
Ipsize,?p8pt,7rrk~,7bls.?ndirs,7offl,7ncksl 


Ipaiee is the physical sector size in bytes; 
7p8pt 
is the number of physical sectors per track; 


7trks 
is the number of tracks on the drive; 


Ibls 
is the allocation unit size in bytes; 


7ndirs is the number of directory entries; 
?off 
is the number of tracks to reserve; 


Incke 
is the number of checked directory entries. 


he following example shore the parameters for a standard 
single-density disk drive: 


OPBSSD: DP8 
128.26.77.1024.64.2 


- 
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The DPB macro can be used only when the disk drive is under 
- 
eight megabytea. DPBS for larger disk drives must be constructed by 
hand. 


- 
3.1 
BIOS Svbrovtine Entry m i n t s 


This section describes the entry parameters, returned values, 


and exact reaponsibilllies of each BIOS entry point in the 810s jump 
vector. 
=he routines are arranged by function. 
section 3.4.1 


describes system initialization. 
Section 3.4.2 
presents the 
character 110 funotions, followed by section 3.4.3, 
discueaing the 
disk I/O funotions. seotion 3.4.4 dieousses the BIOS memory select 
and move functions. 
he lase section. 3.4.5, 
discusses the BIOS 
clock support function. able 3-9 shows the BIOS entry points the 
BOOS calls to perform each of the four categories of system 
functions. 
- 
Table 3-9. N n c t i m a l ozg.ni=atim of 8108 Entry m i n t s 
I 
ooerarion 
Function 
I 
- 
I 
System Initialization 
I 
B W T , *BOOT, DBVTBL. DEVINI, DRYTBL, 


Character I/O 


WSP, CONIN, CONOUT, LIST, AUXOUT, AUXIN. 
LISTST, CONOST, AUXIST, AUXOST 
- 
1 
Disk 1/0 
I 


MOVE, XIIOVB. SELIIUI, SBTBNK 
- 
clock Support 


- 


- 


~ a b l e 3-10 Is a summary shoring the CP/M 3 BlOS function 
numbers, jump instruction names, and the entry and return parameters 
o f each jump instruceion in the table, arranged aocording to the 
- 
BIOS function number. 


BOME, SELDSK, SETTRR. SETSEC, SETDlVL, 
REhO, WRITE, SECTEN, MULTIO, PLUSH 


nemory selects and moves 
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0 
B r n 


1 
WBOOT 


2 
CONST 


able 3-10. 
CP/* 3 8x0s Function JW 
Table S-ry 


4 
CONOUT 


5 
LIST 
6 
AUXOUT 


7 
AUXIN 


10 
SETTRK 
11 
SETSEC 
12 
SETDMA 


13 
RElD 


Output 


15 
LISTST 


16 
SECTRN 


17 
CONOST 


18 
AUXIST 


19 
AUXOST 


1 


Input 
NO. 


20 
DBVTBb 


21 
DEVINI 
22 
DRVTBL 


Function 


26 
TIME 
27 
SELUEU 


28 
SETBNK 
29 
XIlOVE 


None 
None 
None 


None 
None 
c-Drive 0-15 
~ = 1 n i t 
sel Flag 


BC=Track NO 
BC=Sector No 
BC=.Dm 
None 


C=Deblk Code 


None 


B C = L O ~ sect NO 
DB=Trana Tbl Adr 
None 


None 


NOne 


RL=Dest Adr 
OE=Source P.dr 
BC=COY"t 
c=Get/set Flag 
A=Hem Bank 
A-Hem Bank 
B=Dest Bank 
C=Source Bank 


None 
NOne 
A-OPFA if ready 
A-OOH if not ready 
A-Con Char 


NOne 
AL=DPA addr 
HL=OOOA if invalid dr. 


NOne 
None 
None 
A=00A if no Err 
A=01H if Non-recov Err 
A=OFPH if media changed 
r=oo* if no Err 
.. - - 
~ 


a.=oi~ if ~ h y s 
Err 


A=O2H if DSk is R/O 
A=OFFH if media ohanaed 
A=OOH if not ready 
A-OFFH if ready 
HL=Phys Sect No 


R-OOH if not ready 
A-OPPH if ready 
&=ODE if not ready 
A=OPFH if ready 
a-008 if not ready 
&=OFFA if ready 
m=Chrtbl addr 
None 
HL-DrV Tbl addr 
HL=OIIIPA 
HL=OFFIEH 
None 
A=oOOH if no err 
A=OOIH if phys err 
a=oa2s if disk R/O 
WL L DE point to next 
bytes following H O W 


NOne 
None 
None 
None 
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3.4.1 
system lnitialirarion runctions 


This section defines the BIOS system initialization routines 


B W T , WBWT, DEVTBL, DEVINI, and DRVTBL. 


Table 3-10. 
(continued) 


BIOS Function 0: 
BMJT 


and Initialize system 


Returned Values: 
None 


NO. 


=he BWT e n ~ r y 
point gets oontrol from the cold start ~.oader in 


Bank 0 and is responsible for basic system initialization. 
any 


r m i n i n a hardware initialization that is nor done hv the boot ROMS, 
the cold-Boot loader, or the LORBIOS should be perfo;med by the ~cci 
routine. 


30 
USERP 
~eserved for System Implementor 


31 
RESERV~ Reserved for Future Use 


32 
RESERv2 
~eserved for Future Use 


Function 


The BOOT routine must perform the system initialization 


outlined in section 2.3, "system ~nitiqiration: 
=his includes 


initiallzinq Page Zero jumps and loading the CCP. 
B W T usually 


prints a sign-on message, but this can he omitted. control is then 
transferred to the CCP in the TPA at 0 1 0 0 ~ . 


Input 


TO initialize Page zero, the e m routine must plaoe a jump at 
location OoooH to 610s-base + 3, the 810s warn start entry point. 
he BWT routine must also place a jump instruction a t location 
00058 to the address contained in the System Control Block variable, 
IMXTPA. 


The B W T routine nust establish its own stack area if it calls 
any BMS or BIOS routines. ~n a banked eystern, the stack is in ~ a n k 
0 when the cold BM)T routine ia entered. 
he staok must be placed 


in comon ae",ory. 
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E n t r y Parameters: 
None 


Returned Values: 
None 


=he W B m e n t r v o o i n t i a e n t e r e d when a warm s t a r t occurs. A 
. . 


warmstart L S performed rhsncvcl a ~ s e r 
pcogran sranchcs t o l o c a t i o n 


OOOOH 01 .tLCRPt. 
ro return to t h e CCP. 
The WBOOT r o u t i n e must 


perform the system l n l r l a l i a a t l o n o u t l l n e d ~n BIOS F ~ n c f l o n 0. 
~ n c l u d l n q ~ n l c l a l l z l n q ~ a q e 
z e r o lumpe and loadlnq t h e CCP. 


When your m o m r o u t i n e is oomplate, it must t r a n s f e r o o n t r o l 


t o t h e CCP a t l o c a t i o n OlOOA i n t h e TPA. 


Note t h a t t h e CCP d o c s n o t r e s e t t h e d i s k system a t warm s t a r t . 
The CCP r e s e t s t h e d i s k syatem when a CTRL-C is pressed f o l l n r i n g 
t h e system prompt. 


~ o t e 
a l s o t h a t t h e BIOS s t a c k must be i n cornon memory t o make 
BDOS f u n c t i o n c a l l s . 
Only t h e BWT and W B m r a u t i n e e can perform 


BOOS f u n c t i o n c a l l s . 


I f t h e WBWT r o u t i n e is reading t h e CCP f r m a f i l e , it must 


set t h e rnultisecror I/o count, @mTIO i n t h e system C o n t r o l Block, 
to t h e number o f 128-byte records t o be r e a d i n one o p e r a t i o n before 
reading CCP.COM. 
You can d i r e c t l y s e t QMLTIO I n t h e SCB, or you can 
c a l l BWS Function 44 t o s e t t h e l n u l t i s e c t o r count i n t h e SCB. 


r f blocking/deblocking i n done i n t h e BIOS i n s t e a d o f i n t h e 


BOOS, the ~ O O T 
r o u t i n e must d i s c a r d a l l pending b u f f e r s . 


Returned Values: 
EL-addrees of C h r t b l 


The DEVTBL and DWINI e n t r y p o i n t s a l l o w you t o Support devise 
a s s i g n m e n t with a f l e x i b l e , y e t complekely o p t i o n a l system. 
1t 


r e p l a c e s t h e IOBYTE f a c i l i t y o f CP/M 2.2. 
Note t h a t t h e CRRTBL must 


be i n common i n banked systems. 
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Returned Values: 
None 


The DBVINI routine initializes the ohvsical character device 


specified in register c to the baud rate contained in the 
appropriake entry of the CHRTBL. 
1t need only be supplied if I/O 


redirection has been implemented and is referenced only by the 
DEVICE utility supplied with CP/M 3. 


6106 Function 22: 
DRYTBL 


Return address Of Disk Drive Table 


Entry Parameters: None 


Returned values: 
n ~ i ~ d d r e a a 
o f Drive Table o f Disk 


Parameter neaders (OPA)I nashing can 
be utilized if specified by the DPHs 
referenced by this DRVTBL. 


RL-OPPPPB if no Drive Tablei GENCPM does 
not set up buffers. 
Ranhing is 
supported. 


RL-OFrrEA if no Drive Table; GENCPM does 


nok set up buffers. 
Hashing is not 
supported. 


The first instruction of this subroutine must be an 1x1 


H.<addrese> where <address> is one of the above returned values. 
The GENCPM Utility acceseen Che address in this instruction to 
looate the drive table and the disk parameter data structures to 
determine r h m h system configuration to use. 


If you plan to do your own blosking/deblocking, 
the first 
instruction of the DRVTBL routine must be the following: 


1xi 
h,OFPFBh 


You must also set the PSB and PSM fields of the associated Disk 
Parameter lock to zero. 
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3.4.2 
Character I/O ~uactions 


his section define8 the CP/M 3 charaoter I/O routines CONST, - 


CONIN, CONOUT, LIST, AUXOUT, AUXIN, LISTST, CONOST, AUXIST, and 
AUXOST. 


CP/M 3 assumes 
all simple character I/O operations are - 


performed in eight-bit ASCII, upper- and lowercase. with no parity. 
a n a ~ c l r 
CTRL-z ( 1 ~ s ) 
denotes an end-of-file condition for an input 
device. 


1n CP/M 3. you can direct each of the five logical character 
devices to any combination of up to twelve physical devices. Each 
of the five logical devices has a 16-bit vector in the System 
Control ~ 1 0 c k (SCB). ~ a c h 
bit of the vector represents a physical 
device where bit 15 corresponds to device zero, and bit 4 is device 
eleven. 
Bits 0 through 3 are reserved for future system use. 


YOU can use the public names defined in the supplied SCB.&SM 


file to reference the I/O redirection bit vectors. 
The names are 


shown in Table 3-11. 


Table 3-11. 
I/O 
Redirection Bit Vectors in SCB 


~ a m e 
I 
Loaical Device 
1 


@ C I W C 
Console Input 


@ C O W C 
COnSole output 


@AIVEC 
~wxiliary input 


@AOVEC 
Auxiliary Output 


RLOVEC 
List OUtDYt 


YOU should =end an output character to all of the devices whose 
corresponding bit is set. an input character should be read from 
the first ready devioe whose corresponding bit is set. 


An input status routine should return true if any selected 


devioe is ready. ~n output status routine should return true only 
if all selected devices are ready. 


- 
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~ n t r y 
Parameters: None 


Returned value: 
A-OFFA i f a console character 


i s ready t o read 


li=oOH i f no console character 


- 
Read the s t a t u s of the currently assigned console devlce and 
return 0- 
i n r e g i s t e r A if a character i s ready to read, and 00" 


i n r e g i s t e r A i f no coneole characters are ready. 


Returned values: 
A-console Character 


~ e a d 
t h e next sonsole character i n t o r e g i s t e r A with no parity. 
- 
I f no conaole c h a r a c t e r i s ready, 
wait u n t i l a character is 


available before returning. 


Returned Values: 
None 
- 


Send t h e character in r e g i s t e r C to the console output device. 
The character i s in ASCII with no parity. 
- 
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Ontput Character t o L i s t Device 


Returned Values: 
None 


Send the character from register C ko the l i s t i n g devise. The 
character i s in ASCII with no parity. 


Output a Character to t h e 


~ n t r y 
parameters: 
C-character 


Send t h e character from register c t o the currently assigned 


AUXOUT devioe. 
=he character i s in ASCII 
with no parity. 


Read a Character from the 
~ u x i l i a r y Input Device 


Bntry Parameters: None 


Read the next character from the currently assigned huxIN 


device i n t o register A with no pariey. 
a returned ASCII CTRL-z 


(11U1) report. an end-of-file. 
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I 
BIOS Function 15: 
LISTST 
I 


I 
Return the Ready status of the List Device 
I 


/ Entry Parameters* None 
I 


Retuzned Values: 
A-0008 if list devioe is not 
ready to accept a character 


A-OFFH if list devioe ie 


ready LO accept a charcioter 
- 
- 


The BIos LISTST function returns the ready status of the '1st 


device. 


I 
Return Output Status of Console 
/ 


Bntry Parameters: None 


Returned values: 
A-OFPA if ready 
A-008 
if not ready 


he CONOST routine checks the status of the console. CONOST 


returns an OFPB if the console is ready to display another 
character. This entry point allows for full polled handshaking 
comunications support. 


Bntry Parameters: 
None 


Returned Values: 
a-OIPH if ready 
1-0008 if not ready 


The AUXIST roatine checks the input status of the auxiliary port. 
m i a entry point allows full polled handshaking for comunioationa 
support using an auxiliary part. 
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Entry Parameters: 
None 


Retucned values: 
A-OIFR if ready 


=he AUXOST routine checks the output status of the auxiliary 
pore. 
Thls routine allows full polled handshaking for 


~ornuni~ations 
support using an auxiliary port. 


3.4.3 
Disk I/O Funetionll 


his section defines the CP/M 3 BIOS disk I/O routines HOIIB, 


SELDSK. SETTRK, SETSEC. SETDW, -D, 
WRITE, SECTRN, UULTIO, and 
FLUSH. 


Returned Values: 
None 


~ e t u r n the disk head of the currently selected disk to the 


traok 00 position. usually, you can translate the H O W call into a 
call on SETTRK with a parameter of 0. 
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Entry Parametera: C-~isk Drive (0-151 


E-Initial Select Flag 


Returned Values: 
HL-Address of Disk Parameter 


Beader (DPR) if drive exists 


Select the disk drive specified in register c for further 
operations, where register C contains 0 for drive u. 1 for drive 8, 
and so on to 15 for drive P. 
On each disk select, SELDSK muse 


return in HL the base address of a 25-byte area called the ~ i s k 
Parameter Header. 
1f there is an attempt t o select a nonexistent 


drive, SELDSK returns HL-OOOOA as an error indicator. 


on entry to SILDSK, you can determine if it in the first tine 
the specified disk is selected. Bit 0, the least significant bit ~n 
register E, in set to 0 if the drive has not been previously 
Belected. 
his information is of interest in systems that read 


configuralion information from the disk to set up a dynamic disk 
definition table. 


When the B 
m 
calls SELDSK with hit 0 in regiecer e set to 1, 


SELDSK muat return the sane ~ i s k 
Parameter Header address as it 
returned on the initial call to the drive. SELDSK can onlv return a 
OOOH indioating an unsucoesaful select on the initial sgiect call. 


SELDSK must return the address of the Disk Parameter Header on 


eachcall. Postpone the actual physical disk select operation until 
a READ or WRITE is performed, unless I/O is required far automatic 
density-sensing. 


BIOS Function 10: SETTRK 


Entry Parameters: BC=Track Number 


Returned Values: 
None 


Register BC contains the track number for a subsequent disk 


access on the currently selected drive. Normally, the track number 
la saved until the n e x t m 
D 
or WRITE occurs. 
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Returned values: 
None 


Register BC contains the sector number for the subsequent disk 


acoess on the currently selected drive. 
=his number is the value 
returned bv SECTRN. usuaiiv. vou delav actual sector selection 


810s Function 12: S E T D ~ 


Sea Address for subsequent Disk I/O 


entry parameters: 
~ c = ~ i r e c t 
Memory 


A C C ~ S S ~ d d r e s s 


Returned Values: 
None 


Register BC contains the Dna (Direct Memory Ascesel address for 
the subsequent READ or WRITE operation. Por example, if B - OOR and 
c - 80R when the BWS calls S E T O ~ , then the subsequent read 
operation reads its data starting a t 80R, or the subsequent write 
oneration gets its data from eon, until the next call to S E T D ~ 
O c C Y r O . 
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Entry Paralnetera: None 


Returned values: 
A=0008 if no errors occurred 
A-001H if nonrecoverable error 


condition accurred 


A-OPIH if media has changed 


Assume the B W S has selected the drive, set the track, set the 


Sector, and speoified the D m address. The READ subroutine attempts 
to read one rector based upon these parameters, then returns one of 
the error codes in register A as described above. 


If the value in register A is 0, then CP/n 3 assumes that the 


disk operation completed properly. 
If an error occurs, the BIOS 


should artemnt several retries to see if the error is recouerahl- 
before returning the error code. 


~ 
- 
- 
~ 
~ 
- 
.--... 


If an error occurs in a svstem that suomrts automatic densitv 
- - 


selection, the system should Gerify the d&sity 
of the drive. 
1; 


the density has changed, return a OPPH in the aocunulator. 
his 


oauses the B W S to terminate the current operation and r e l q in the 
disk. 


write a Sector to the Specified ~ i s k 


Returned values: 
A-000n if no error occurred 
A=001H if physical error occurred 
A-002H if disk is Read-Only 


Write the daka from the cvrrently selected D m address t o the 


cur~ently elected drive, track, and sector. 
Upon each call to 
WRITE, the BDOS provides the following information in register C: 


0 = deferred write 
1 = "ondeferred write 
2 = deferred write to the first sector of a new data block 
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This information is provided for those BIOS implementations that do 
blocking/deblooking in the BIOS instead of the BDOS. 
- 


AS in REm, the BIOS should attempt several retries before 
reporting an error. 


I€ an error occurs in a system that supporta automatic density - 


:;:"~R,;;yt~,"',"~;."dhh~",'."t;~;'a"O;,"x' 
;y:.'YazE";;,";b;gr'r'Th;: 


causes the BOOS to termmate the current operation and relog in the 
disk. 
- 


1 
BIOS Function 16: 
SECTRN 
I 
- 


Translate Sector Number Given Translate Table 


OE=Translate Table address 


~eturned 
values: 
~ ~ ~ ~ h y s i c a l 
sector Number 


SECTRN performs logical sequential sector address to physical 
sector translation to ~mprove the overall response of CP/M 3. 
Digital Research ships standard CP/M disk with a skew factor of 6, - 
where six physical sectors are skipped between each logical read 
operation. his skew factor allows enough tine between sectors for 
most programs on a slow system to process their buffers without 
missing the next sector. 
1n computer systems that use fast 
processors, memory, and disk subsystems, you can change the skew - 


fact01 to improve overall response. 
Typically, most disk systems 


a skew factor of 6 in your CP/M 3 system to allow informatLon - 
transfer to and from other CP/M users. 


lock foc the currently selected disk. The sector number is used as 
an index into the translate table 
vith the resulting physlcal 


sector number returned in HL. 
FOX s;andard, single-density, eight- 


inch disk systems, the tables and indexing code are provided in the 
sample BIOS and need not be changed. 


Certain drive types either do not need skewing or perform the 
skewing externally from the system software. In this case, the skew 
table address in the DPH can be set ko zero, end the SECTRN routine - 


can check for the zero ~n DE and return with the physical sector set 
to the logical sector. 


- 
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- 


S e t Count of Consecutive s e c t o r s 


for R E I D or WRITE 
- 
- 


TO t r a n s f e r l o g i o a l l y oonsecutive d i s k s e c t o r s t o or f r m 


~ ~ n t l g ~ ~ ~ e r n e a o r y l ~ a t i o n n , 
the BDOS issues a MULTIO c a l l , followed 


by a s e r i e s of READ or WRITE c a l l s . 
This allows the BIOS 
t o 
transfer multiple s e c t o r s i n a s i n g l e disk operation. 
The maximum 
value of the sector count i s dependent on the physical sector s i z e 
ranglng from 128 with 128-byte s e c t o r s , t o 4 with 1096-byte oectors: 
Thus, the BIOS can t r a n s f e r up t o 16K d i r e c t l y t o or f r a n t h e T P ~ 
with a single operation. 


The BIOS can d i r e c t l y transfer a l l of t h e specified s e c t o r s t o 


or from the Dm buffer i n one operation and then count down the 
- 
remaining c a l l s t o m u or WRITE. 


I f the d i s k Eormat uses a skew t a b l e t o minimize r o t a t i o n a l 


When en error =curs during a multisector t r a n s f e r 
you can 
- 
either r e s e t the multiple seotor counters i n the 810s and i e t u r n the 
error i m e d i a t e l y , or you can save the error s t a t u s and r e t u r n it to 
the BDOS on the l a s t RGAD or WRITE c a l l of the m T 1 0 operation. 
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m r c e ~hysical 
Buffer Flushing 


Entry Parameters: None 


~eturned values: 
1=000H if no error occurred 
A - 0 0 1 ~ if physical error occurred 


=he flush buffers entry point allows the system to force 
physical sector buffer flushing when your BIOS is performing its own - 
record blocking and deblocklng. 


The BDOS calls the PLUSH routine to ensure that no dirty 
buffers remain in memory. 
he BIOS should immediately write any - 


buffers that contain unwritten data. 


~onnally, the PLUSH function is superfluous, heoavae the B W S 


supports hlocking/deblocklng internally. 
1t ia required, however. 


for those systems that support blocking/deblocking in the BIOS, as - 
nuany CP/M 2.2 systems do. 
-: 
if you do nor implement PLUSR, the routine must return a zero 


in register A. 
YOU can accomplish this with the following - 


instr"~tiO"(l: 


xra 
a 


ret 
- 


3.4.4 
Memory select and M 
e 
Purrti- 


p his section deflnee the menory management functions MOVE, - 


Xnm, SELMBM, and SETBNK. 
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Entry parameters: memory Bank 


Returned Values: 
None 


he s E L m n entry point 1s only present in banked systems. me 


banked version of the CP/M 3 BWS calla SELMEM to select the current 
memory bank for further instruction execution or buffer references. 
YOU muat preserve or restore all registers other than the 
a ~ ~ ~ m u l a t o r , 
A, upon exit. 


BIOS Function 28: 
SETBNK 


specify ~ a n k 
for D m Operation 


entry ~nraneters: 
a.=Memory Bank 


SETBNK Only occUrn in the banked version of CP/M 3. 
SETBNK 
specifies the bank that the subsequent disk 
or WRITB routine 


must use for memory transfers. 
The BOOS always makes a call to 


FETBNK to identify the DMA bank before performing a m 
o 
or WRITE 


call. ~ o t e 
that the BOOS does not reference banka other than 0 or 1 
unless another bank is specified by the BANK field of a Data Buffer 
Control Block (BCB) . 


BIOS Function 29: M O V E 


Set Banks for F~llowing MOVE 


Entry Parameters: 
B=destinetion bank 
C-SOYTCe bank 


~eturned Values: 
None 


MOVE is provided for banked systems that support memory-to- 
memory DHR transfers over the entire extended address range. 
systems with this feature can have their data buffers located in an 
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alternate bank instead of in cornon memory, as is usually required. 
An VIOVE call affects only the following MOVE 0.11. 
A11 subsequent 


MOVE calla apply to the aelnory selected by the latest call to 
S E L m . After a call to the VIOYE function, the following oall to 
the ~XNE funotion ia not more than 128 bytes of data. 1f you do not 
implement WOVE, the first instruction must be a RBT instruction. 


3.4.5 
Cl-k 
s v p p ~ r t 
Puaction 


This section defines the clock svpport function TIME. 


BIOS Function 26: TIME 


Entry Parameters: C-~ine ~et/set n a g 


Returned ~alues: None 


The BDOS calls the TIME function to indicate to the BIOS 


r 
t 
s 
t 
i 
d 
;Ie;d:=g ;;: g.. 
z; 


entry to the TI= function, a zero in register C indicates that the 
BIOS shollld update the Time and Date fields in the SCB. A OFPH in 
rqisterc indicates that the BDOS has just set the Tine and Date in 
the SCB and the 610s should update its clock. 
Upon exit, you nuat 


restore register pairs EL and DE to their entry values. 


3.5 
Banking Considerations 


This section discusses considerations for separating your BIOS 
into resident and banked modules. 
You can place part of your 


ust to mi led BIOS in cornon memory, and part of it in Bank 0. 
Rowever, the follaring data structures and routines must remain in 
cornon memory: 
. 
the BIOS stack 
. 
the BIos jump vector 
. 
Disk Parameter B l o ~ k s 
. 
memory management routines 
. 
the CRRTBL data structure 
all character I/O routines 
. 
portions of the disk I/O rourines 
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YOU can place portions of the diak I/O routines in the system 
bank sank 0 
~n a banked environment 
if the diak I/O hardware 


sYpP;)rts ~ m ' t r a n s f ~ ~ ~ 
to and f r m ban<e other than the currently - 


selected bank the disk 1/0 drivers can reside in Bank 0. 
If the 


~ystem 
has a D I ~ . controller that supports block lnoves f r m memory to 


memory between banks CP/M 3 also a l l a a you to place the blocking 
and deblocking buffka in any bank other than Bank 1, instead of - 
oommon memory. 


I£ your disk oonrroller svpporrs data transfers only into the 


~urrently eelected bank, then the code that initiates and performs a 
data transfer must reaide in common memory. In this case, the disk 
I/O transfer routines must select the o m bank, perform the 
transfer, rhen reselect ~ a n k 
0. 
he routine in common memory 


performs the following procedure: 


1) Selects the D m bank that SBTBNK saved. 
2) Performa physical I/O. 
3) Reselects ~ a n k 
0. 


I ) Returns to the Falling READ or WRITE routine in Bank 0. 


Nore that ~ a n k 
0 is in context (selected) when the B W S calls 
the system initialization functions B W T and DRVTBL; the disk 1/0 
routines HOME, SELDSI, SETTRK, SETSEC. S E T D ~ , 
m u . ~ I T E . 
SECTRN. 


MULTTO, and PLUS"; and the memory management routines XnOVE and 
SETBNK. 


nmk n or Rink 1 is in context rhen the B W S calls the system 
.- 
. . . 
initialization routines WBODT DEVTBL, and DEVINI~ 
the character I/O 


routines CONST, CONIN, CONOUT: LIST, AUXOUT, AUXIN, LISTST, CONOST, 
LIIYTST. 
m d &U.UXOST. the memorv select and move routines Mom and 
............... 
SELMEM, and the clock support >outin= TIME. 


YOU can place a portion of the character I/O rovtines in Bank 0 


if you place the following procedure in common memory. 


1) swap stacks to a local stack in common. 
2 ) Save the current bank. 
:1 
5',:;':hEkpkpriate 
~haracter I/o routine. 
5) Reselect the saved hank. 
61 Restore the stack. 


- 
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- 
3.6 
A s e d l i a ~ 
and Linking Tour BIOS 


This Section assumes you have developed a BIOS3.ASI or 


BNKBIOS3.ASU file appropziite toyour specifio hardware eeeironnnnt. 
Use the Digital ~esearch Relocatable Macro Atlscmbler WC' 
to 
- 
assemble the BIOS. 
use the Digital Research Linker LINK-8O"to 


create the BIOS3.SPR and BNKBIOS3.SPR files. The SPR files are part 
of the input to the GENCPM program. 


- 
In a banked enviroment, your C P M 3 810s can consist of two 
segments: a banked segment and a co-n 
segment. This allows you 
to minimize common memory usage to maximize the size of the W A . TO 
prepare a banked BIOS, place code and data that Rust reside in 
nxoron in the CSEG segment, and code and data Chat can reside in the 
_ 
System bank in the DSBG segment. when you link the BIOS, LINK-80 
creates the BNKBIOSP.SPR file with all the CSBG code and data first, 
then the DSEG code and data. 


lfter assembling the sros with W C , link your BNRBIOS using 


LINK-80 with the 181 option. The 181 option aligns the DSEG on a 
page boundary, and places the length of the CSEG into the 
BNRBIOS3.SPR header page. 


use the following procedure to prepare a B I o s 3 . s ~ ~ 
or 


BNRBIOS3.SPR file f r m your oustmired 8108. 


11 Assemble your BIOS3.ASI or BNRBIOS3.ASM file with the 
relocatable assembler mc.COM to produce s relocatable 
file of type RBL. 
~ s s e n b l e SCB.ASM 
to produoe the 
relocatable file SCB.REL. 


Assembling the Nonbanked BTOS: 


A>- 
81063 


Assembling the Banked BIOS: 


A>- 
BIIKBIOS3 


21 Llnk the BIOS3.REL or BNKBIOS3.REL file and the SCB.REL fllc 


rlfh LINK-80 Lo produce tne RIOS3.SPRor BNKBIOS3,SPR flle. 
The losl optron vlrh L I N K cadsea the o u t p ~ t of a system 
Page RelOCatablF lSPRl flle. 


Linking the Nonbanked BIOS: 


A>L111K 81053 I051 -8IOS3,SCB 


Linking the Banked BIOS: 


A>LIEK B.KB1083IBl-BWI083,SCB 
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Thepreceding examples show c m a n d lines for linking a banked 
and nonbanked BIOS. 
I n these exenplea. the BIOS3.RBL and 


BNWIOS3.REL are the files of your assembled BIOS. SCB.RBL contains 
- 


the definitions of the System Control Block variables. 
The IB] 


option implies the [OSI option. 


End of Section 3 
- 


- 
Section 4 


CP/M 3 Sample BIOS Modules 


- 


This section disou~ses the rnodvla~ organization of the example 


CP/M 3 BIOS on your distribution disk. Por previous CP/M operating 
systems, it was necessary to generate all input/output drivers from 
- 
a single assembler eouroe file. 
such a file is difficult to 


:"i',:'c; 
~yd~P,9p&~,"t'h'."1B,"o';i~~~="c;"/; 
pi: :::-::i 


small nodules. 
- 
The organization of the BIOS into separate modules allows you 


to write or modify any 1/0 driver independently of the other 
modules. aor example, you can easlly add another disk 1/0 driver 
for a new controller vith minimum impact on the other parts of the 
- 
810s. 


- 
The modules of the BlOS are BIOSKRNL.ASM, SCB.ASM, 800T.ASM. 


MOVB.ASM, CBARIO.ASM, DRVTBL.ASM, and a disk T/O module For each 
supported disk controller in the configuration. 


810SKRNL.ASM is the kernel, root, or supervisor module of the 
- 
BIOS. The SCB.ASM module contains references to locations in the 
System Control Block. 
You can customize the other modules to 


s-rt 
any hardware configurat~on. To customize your system add 
or modify external modules other than the kernel and the SC;.ASM 
- 
module. 


Digital Research supplies theBIOSRRNL.ASnmodule. This module 


is the fixed, invariant portion of the 810s. and the interface from 
- 
the B 
m 
to all 510s functions. It is supplied in source form For 
reference only, and you should not modify it except for the equate 
Statement described in the fallowing paragraph. 


YOY must be sure the equate statement (banked equ true) at the 
- 
start of the BIOSRRNL.ASM source file is oorrect for yon. 
system 


configuration. Dlgital Research distributes the BIOSKRNL.ASM file 
for a banked system. 
I£ you are creating a BIOS for a nonbanked 


System, change the equate statement to the following: 
- 
banked equ false 


and reaaselnble vith RWLC. Thin is the only change you should make 
- 


to the BIOSKRNL.ASM File. 


able 4-1 sunmarires the modules in the CP/M 3 BIOS 
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Module 
Function 


B10SKIWL.RSM 


~ e r f o r m e basic system initialization, and 
dispatches charaoter and disk I/O. 


contains the public definitions of the 
various fields in the system Control slock. 
The BIOS can reference the public variables. 


perform. 
system initialization other than 
character and disk 1/0. BW 
loads the CCP 


€01 cold starts and reloads it for warm 
starts. 


CRARIO.ASM module 


Perform8 allcharactec dddiie initialization, 
input, ovtput and status polling. 
CE'ARIO 


contains the cdar8cter dddiie chhracteeiitics 
table. 


DRVTBL.ASM module 


points t o the data structvres for each 
configured disk drive. 
The drive table 


d e t e m i n e s which physical disk unit is 
asaoclated with which logical drive. 
The 
data structure for each disk drive is called 
an Extended Disk Parameter Header IXDPH). 


~ i a k 
I/O nodules 


initialize disk controllers and execute READ 
and WRITE code for disk controllers. 
You 


muse provide an XDPH for each supported unit, 
and a separate disk I/O module for each 
controller in the system. 
TO add another 
disk controller for which a prewrittenmdule 
exists, add its XDPH names to the DRVTBL and 
link in the new module. 
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3) SIOSKRNL calls the ?INIT entry of the BOOT module to 
initialize other system hardware, such as memory 
~ontrollers, interrupts, and clacks. 
1t prints a sign-on 


message specific to the system, if desired. 


4) BIOSKRNL calls ?LOCCP in the BCOT module to load the CCP 
into the TPA. 


51 The BIOSKPNL lnodvle sets up Page Zero of the TPA with the 


appropriate jump vectors, and passes control to the CCP. 


4.3.2 
Character I/O Operation 


=he CHIRIO module performs all physical character I/O. 
his 


module contains both the character device table (@CTBLl and the 
routines for character input, output, initialization, and status 
polling. The character device table. BCTBL, contains the ASCII name 
of each device, mode information. and the current baud rate of 
serial devices. 


TO support logical to physical redirection of character 
devices, CP/M 3 supplies a 16-bit assignment vector for each logical 
device. 
The bits in these vectors correspond to the physical 


devioea. 
=he character I/O interface routines in BIOSKRNL handle 
all device asslgnmenr. calling the appropriate character f/O 
routines with the correct devioe number. The BIOSKPNL module also 
handles xoN/xorr processing on output devices where it is enabled. 


YOY can use the DEVICE utility to assign several physical 


devioea to a logical device. 
The BTOSRRNL root module polls the 


assigned physical devices, and either reads a character £ran the 
first ready input device that IS selected, or sends the character to 
all of the selected output devices as they become ready. 


4.3.3 
Disk I/O Operation 


TheBIosKRNLmod~le h a n d l e s a l l ~ ~ o s 
calls associated withdisk 


110. 
I= initializes global variables with the parameters for each 
operation, then invokes the READ or WRITE routine for a particular 
controller. 
The SELDSK rourine in the BlOSKRNL calls the LOGIN 
routine for a controller when the B W S initiates a drive login. 
his allows disk density or media type to be automatically 
determined. 


~ h e ~ ~ ~ ~ ~ ~ m o d u l e 
contains the sixteen-word drive table. @DTBL. 


he order of the entries in @DTBL derermlnes the logical to physical 
drive assignment. ~ a c h 
vord in BOTBL contains the address of a DPH, 


whioh IS part of an xDPH, as shown in =able 4-10. The word contains 
a zero if the drive does not exist. The XDPH contains the addresses 
of the INIT, LODIN, RBIID, and WRITE entry points of the 1/0 driver 
for a partlcvlar controller. when the acrval drivers are called, 
globally accessible variables contain the various parameters of the 
operation, such as the track and sector. 


- 
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- 
4.4 
Predefined variables and subrwtinea 


The modules of the BIOS define public variables which other 


d u l e s can reference. Table 4-2 contains a summary of each p u b l ~ c 
symbol and the nodule that defines it. 
- 


Table 4-2. 
Public Symbols in CP/M 3 8108 


Character device input 
Character device initialization 
Character device inout statvs 


- 
- 
- 


Character device outout 


@ADRV 
Byte. Absolute drlve code 


@CBNK 
Byte, current CPU bank 
BIOSKRNL 


BCNT 
Byte, Mvltisector count 


BIOSRRNL 


BCTBL 
Table, Character device table 


BIOSKRNL 


BDBNK 
Byte, Bank for disk 1/0 


CHAR10 


BDMA 
Word, D m address 
BIOSKRNL 


BDTBL 
Table, Drive table 


BTOSKRNL 
DRYTBL 


BRDRV 
Byte, Relative drive code (UNIT) 
BTOSKRNL 


@SECT 
Word, Sector address 


BTRK 
Word, Track number 
BIOSKRNL 
BlOSKRNL 


Character d e v i o o;Gu; 
status 


General lnitialiratian 
Load CCP for cold stare 


Svrnt-31 


Move memory to memory 
Print decimal number 
Print 610s disk error header 
Print message 
Reload CCP for warm start 
Set banks for extended move 
set or Get t1.e 


MOVE 
CHARTO 
CHARIO 
ClI&RIO 
CHlRIO 
CHARIO 
BOOT 
BOOT 


MOVE 
BiOSKRNL 


BlOSKRNL 
BlOSKRNL 
BOOT 
HOVE 
BODT 


Function and Use 


- 
- 
he system control m o c k defines public wriables that other 


nodules can reference. he System Control lock variables CCIYEC 
@ m C . CAIVEC, CAOVEC, and CLOVEC are referenced by BIOSKRNL.I\SH: 
The variable BBNKBF can be used by 7LDCCP and 7RLCCP to implement 
- 
interbank block moves. 
The public variable names BERnDE 


(RESEL, @YIBIO, BCRDSK, BUSRCD, and BCRDHI are used forre:::: 
;;;;yi"'~w"@;", 
i~ne';~~:$,",",","~ey;~; i:;:,;:;z:i:z:;gr;y;; 


clock. 
BMXTPA contains the current B W S entry point. 
- 


Disk I/O operati~n parameters are passed in the fallowing 


global variables, as shown in Table 4-3. 


Defined 
in Mod,,,. 


CP/M 3 syeten Guide 
4.4 
predefined variables and Subroutines - 


- 


Several utility subroutines are defined in the BIOSRRNL.ASl4 


module, as s h a n in Table 4-4. 


=able 4-3. 
Global variables in BIOSlmUL.NU 


vaciable 


Table 4-4. 
Public utility Subroutines in BIOSlmUL.NI 
- 


- 


Meaning 


utility 
Meaning 


?PMSG 
print string starting at <HLI, stop at null 
(0). 


@ADRV 
Byte; contains the absolute drive code (0 
through P fox A through PI that CP/M is 
referencing for READ andsrRITE operations. The 
SELOSR routine in the BIOSRRNL !nodule obtains 
this value from the BDOS and places it in @DRV. 
he absolvte drive code is used to print error 
messages. 


eRDRV 
Byte: contains the relative drive code for READ 
a n d m I ~ E 
operations. he relative drive code 
is the UNIT number of the controller in a given 
disk 1/0 module. 
BIOSKRNL obtains the unit 


n u w r from the XDPH. This is the actual drive 
code a d r ~ v e r should send to the controller. 


@TRK 
word; contains the starting track for READ and 
WRITE. 


@SECT 
WDrd; contains the starting sector for READ and 
WRITE. 


@ o m 
word; contains the starting disk transfer 
address. 


@DBNR 
~ y t e ; 
contains the bank of the D m buffer. 


@CNT 
syrei contains the physical sector count for 
the operations that follw. 


PCBNR 
Byte; contains the current bank for code 
execution. 


1 
?PDEC 
Print binary number in decimal from HL. 
I 


I 


w 
D 
m 
rrint disk error w s u e header using current 
disk parameters, <CR><IB>BIOS Error on d:. T- 
nn. S-nn. 


- 
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All BIDS entry points in the jump vectoc are declared as public 
- 
for general reference by other 610s modules, as shown in =able 4-5. 


- 


- 


The BOOT nodule performs general system initialization, and 
loads and reloads the CCP. Table 4-6 shows the entry points of the 
BOOT module. 


Table 4-5. 
Public B a u s in the BlOg Jump Vector 


Public Name 
Punceion 


7 E W T 
Cold b w r entry 


?IPBM)T 
Warn book entry 


?CONST 
Console input status 


?CONIN 
Console input 


?CON0 
Console output 
?LIST 
List output 


?AUXO 
Auxil~ary output 


?AUXI 
?HOME 


aulli1iary input 
Home disk drive 


1SLDSK 
Select disk drive 


?ST.IIRK 
Set track 


?STSEC 
Set sector 


?STDIUL 
see o m address 


?READ 
Read record 
?WRITE 
Write record 
?LISTS 
List status 


?SCTRN 
Translate rector 


?CONOS 
Console output status 


?AUXIS 
~ux~1ia.y m p u t status 


1AUXOS 
AYxi1ia1-y output status 


?DYTBL 
Return character device table address 


?DEVIN 
Initialize character device 


?DRTBL 
Return disk drive table address 


?MLTTO 
Set multiple sector count 


?FLUSH 
Flush deblocking buffers (not implemented) 


?MOV 
?TI" 


Move memory block 
Signal set or get time from olock 


?BNKSL 
Set bank for further execution 


1STBNK 
see bank for DMA 


?WOV 
Set banks for next move 
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T a b l e 4-6. 
BOOT m u l e E n t r y P o i n t s 


n o d u l e 


FINIT 


BlOSKRNL c a l l s ?LDCCP d u r i n g c o l d start to 
l o a d t h e CCP i n t o t h e TPA. 
The CCP can be 
l o a d e d e i t h e r from t h e s y s t e m t r a c k s of 
t h e Mot d e v i c e or from a f i l e , a t t h e 
discretion o f t h e s y s t e m implementor. 
1x1 


a banked system, you Can p l a c e a c o p y of 
t h e CCP i n a r e s e r v e d area o f a n o t h e r bank 
to i n c r e a s e t h e performance of t h e ?RLCCP 
r o u t i n e . 


?RLCCP 
BIOSKRNL c a l l s ?RLCCP d u r i n g warm s t a r t t o 
r e l o a d t h e CCP i n t o t h e TPA. 
I n a banked 


e y s t e m , t h e CCP can be c o p i e d from an 
a l t e r n a t e b a n k t o e l i m i n a t e a n y d i s k 
access. 
O t h e r w i s e , t h e CCP s h o u l d be 


l o a d e d from e i t h e r t h e s y s t e m t r a c k s of 
t h e b o a t d e v i c e or from a f i l e . 


4.6 
C h a r a c t e r I/O 


T h e CHARIO module h a n d l e s a l l c h a r a c t e r d e v i c e interfacing. 


T h e CHARIO module c o n t a i n s t h e c h a r a c t e r d e v i c e d e f i n i t i o n t a b l e 
@CTBL, t h e c h a r a c t e r m p u r routme ?CI, t h e c h a r a c t e r o u t p u t r o u t i n e 
?m, t h e c h a r a c t e r i n p u t s t a t u s r o u t i n e ?CIST, t h e c h a r a c t e r o u t p u t 
s t a t u s r o u t i n e ?COST, 
a n d t h e character d e v i c e l n x t l a l i z a t i o n 


r o u t i n e 1CINIT. 


=he 610s 
r o o t module, BIOSKRNL.ISM, 
h a n d l e s a l l c h a r a c t e r I/O 


r e d i r e c t i o n . 
= h i s module determine. 
t h e a p p r o p r i a t e d e v l c e s t o 
p e r f o r m o p e r a t i o n s and executes t h e a c t u a l o p e r a t i o n by c a l l l n g ?CI, 
?CO, ?GIST, a n d ?COST w t h t h e p r o p e r d e v i c e n u m b e r ( s ) . 


@CTBL IS t h e e x t e r n a l name f o r t h e s t r u c r v r e CHRTBL d e s c r i b e d 
i n s e c t i o n 3 o f this manual. 
@CTBL c o n t a i n s an 8-byte e n t r y f o r 


eaoh p h y s i c a l d e v i c e d e f i n e d by t h i s BIOS. 
=he t a b l e IS t e r m i n a t e d 


by a zero b y t e a f t e r t h e l a s t e n t r y . 


=he f i r s t f i e l d o f t h e c h a r a c t e r d e v i c e t a b l e . @CTBL, is t h e 6- 


byte d e v i c e name. T h i s d e v i c e name s h o v l d be a l l upper-case, 
l e f t - 


j u s t i f i e d , a n d padded w i t h RSCII spaces l20H). 
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he second field of @CTBL is 1 byte containing blte that 
indicate the type of device and its current mode, as shown in able 
4-7. 


ooooooll 
~nplt/output device (such as a terminal 
or modem1 


00000100 
~ e v i c e has aoftxare-selectable baud 
rates 
00001000 
Device may use XON protocol 


The third field of @CTBL ie 1 byte and contains the current 


baud rare for serial devices. The high-order nibble of this field 
is .ese.Md 
for future use and should he set to zero. The low-order 


f w r blre contain the current baud rate as shown in =able 4-8. 
Many 


systems do not support a11 of these baud rate*. 


=able 4-9 shows the entry points to the routines in the CBAFSO 


module. 
he BIOSRRNL module calla theae routines to perform 


nachine-dependent oharaster I/O. 


=able 4-8. 
m u d nates for Serial Devices 


Baud Rate 
~ e c i n a l 


0 
0000 
none 


1 
0001 
50 


Binary 
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able 4-9. 
character Deslce Labels 


Label 
Meaning 


XI 
Character Device ~ n p u t 


?CI is called rith a device number in register 
B. 1t should rait for the next available input 
character, then return the character in 
register a. 
he character should be in 8-bit 


RSCII rith no parity. 


?CO 
Character Device output 


?m is called vith a devioe number in register 
B and a charaoter in register C. 
It should 
rait until the device is ready to accept 
another oharacter and then send the characre;. 
The character is in 8-bit ASCII rith no parity. 


X I S T 
Character Device Input Status 


?CIS= is called with a device number in 
register B. 1t should return with register a 
set to zero if the device specified has no 
input character ready; and should return vith A 
set to DPPA if the device specified has an 
input character ready to be read. 


?COST 
character Device output Status 


?COST is called rith a devise number in 
register B. 
~t should return rith register A 
set to zero if the device specified oannot 
accept a character imediately, and should 
return rith A set to OPPH if the device is 
ready to accept e character. 


I 
1CINIT character Device Initialization 
I 


- 
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4.7 
Disk I/O 


The separation of the disk 1/0 section of the BIOS into several 


modules allows YOU to support each particular disk controller 
independently from the rest of the system. 
A manufacturer oan 
- 
supply the code for a controller in object module form, and you can 
llnk it into any existing nodular BTOS to funotion with other 
controllers in the system. 


The data structure called the Extended Disk Parameter w a d e r 
- 
or XDPH, contains all the necessary information about a disk drive: 
BIOSKRNL.ASM locates the XDPE for a particular logical drive using 
the Drive Table. 
The XDPH contains the addresses of the REaD, 
- 
~,",.l$;;;;a;;;;~~ep~", 
:~~;~:;zy~ph; 
~ 
~ 
~ 
~ 
; 
l 
~ 
~ 
~ 
~ 
; 
; 
a 
; 
; 


media type, and the Disk Parameter Keader (DPRI rhat the BOOS 
requires. 
Section 3 of this manual describes the Disk Parameter 


Header. 


4.7.1 
Disk l/O structure 
- 
The BIOS requires a DRVTBL module to locate the disk driver. 
It also requires a disk module for each controller rhat is 
supported. 
- 
The drive table module, DRVTBL, contains the addresses of each 
XDPR defined in the system. Each XDPR referenced in the DRVTBL must 
he deolared external to link the tahle with the actual disk modules. 


The XDPRs are the only public entry points in the disk 1/0 


nodules. The root module references the XOPHS to locate the actual 
I/O driver code to perform sector M&DS and WRITES. 
When the MAD 


and WRITE routines are called, the parameters controlling the Rsno 
or WRITE Operation are contained in a series of global variables 
that are declared public in the root module. 


1.7.2 
Drive Table nodule [ D ~ L ) 
- 
The drive table nmdule. DRYTBL, defines the CP/M absolute drive 


codes associated with the physical dieka. 


- 
1 6 - ~ ~ ? , " . " ~ , " ~ t ~ , " , " ~ ~ i ~ ~ ~ ~ ~ d " d : e e ~ . " . " ~ ~ ~ f ~ t ~ k 
","?,"d,rn!?Ec; 


XDPR name must be declared external in the DRVTBL. 
The First entry 


corresponds to drive A, and the last to drive P. 
You must set an 


entry to 0 if the corresponding drive is undefined. 
Selecting an 
- 
undefined drive causes a B W S SELECT error. 
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1.7.3 
Extended Disk Par-tar 
Baaderll (XDPRsI 


An Extended Diak Parameaer Reader IXDPRJ consists of a prefix 
and a regular ~ i s k 
Parameter ~ e a d e r 
an described in Seotion 3. he 


label of a XDPR references the start of the DPH. The fields of the 
prefix are looated at relative offsets from the xoPR label. 


=he XDPAa for each unit of a controller are the onlv entrv 


ADDRESS 
LOW BYTE 
HIGH BYTE 


0 
7 8 
5 


ilddr d rector WRITE 


addr of rector READ 
1 


I 
addr of drlve LOGIN 
I 


""t, 
I 
type 


add, Of translate fable 
- 


start 01 


-regular DPH 


addr of DPB 


addr of DTABCB 


addl 01 HASH 


I 
hash bank 
I 


- 
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- 
Table 4-10 describes the fieldsof aachBrtended Disk Parameter 
Header. 


Table 4-10. 
Fields ot Each IDPX 


The -AD word contains the addreas of the 
seator m 
D 
routine for the drive. 


LOGIN 
he LCGIN word contciina the address of the 
LOGIN routine for the drive. 


The TNIF word contains the address of the 
first-time initialization code for the 
drive. 


The UNIT hyte contains the drive code 


- I 


relative to the disk controll.er. his is 
the value placed in @RDRV prior to oalling 
the READ, WRITE, and LCGIN entry points of 
the drive. 
- 
I 


he TYPE hyte is unused by the e m s r m t . 
and is reserved for the driver t o keep the 
current density or media type to support 
multiple-format disk suhsyseemr. 


- I 


regular DPH 
=he renain~ng fields of the XDPH comprise 
a standard DPH, as discussed in Section 3 
of this manual. 
- 


4.7.4 
Subroutine Entry Points 


The pointers contained in the XDPH reference the actual code 
- 
entry points to a disk driver module. 
These routines are not 


dedlared public. 
only the XDPH itself is public. 
=he BIOS root 
references the XDPHS only through the @DTBL. Table 4-11 shows the 
BIDS subroutine entry points. 
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'fable 4-11. 
Sobratine Entry Points 


DE. 
=he parameters for the WRITE 
operation are contained in the public 
variables BkDRV, @RORv, BTRK, @SECT, @ D m , 
and @DBNK. 
The WRITE routine Should 


1etu.n 
an error code in register a. 
The 


code 00 means a successful operation, 01 
means a permanent error occurred, and 02 
means the drive ia write-protected if that 
feature is supported. 


READ 


L W I N 


he REID 
and WRITE routines should perform several retries of 


an opration that pradvcea an error. 
If the error ia related to a 


seek operation or a record not found condition. the retry routine 
can h- 
or restore the drive, and then seek the correct track. The 
exact sequence of events is hardrare-dependent. 
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following message; 


BIOS Err on D: T-nn s-nn 


The D: is the selected drive, and T-nn and S-nn display the track 
and sector number for the operation. 
The -D 
and WRITE routines 


should print the exact cause of the error after this message, such 
88 Not Ready, or Write Protect. 
The driver can then ask the 
operator if additional retries are desired, and return an error code 
to the B W S if they are nor. 


H O W ~ V ~ . , if the e m u m x byte in the system control lock 


indicates the B W S i~ returning error codes to the application 
program without printing error messages, the BIOS should simply 
return an error without any message. 


4.7.6 
multiple Seetor I/O 


The root m d u l e global variable eCNT contains the multisector 


count. 
Refer to sestiona 2.5 and 3.4.3 
for a discussion of the 


conaiaerarions regarding multirecord I/O. 


The MOVE Module ptrforms memory-to-memory 
blook moves and 


controls bank selection. 
=he ?MOW 
and ~XIIOVE entry points 


correspond directly to the MOVE and XMOVE jump vector routines 
doaunented in Section 3. Table 4-12 shows the entry p i n t s for the 
HOVE nodule. 
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Entry Point 
Meaning 


?MOVE 
memory-to-memory m 
e 


?MOVE in called with the source address for 
the move in register DB, the destination 
address in register AL, and the byte count in 
register BC. If ? m o r n ha. 
been called since 
the last call to ?MOVE, an interbank move must 
be performed. 
On return, registers EL and DE 


nust p i n e to the next bytes after the MOVE. 
=his routine can use speoial DM?. hardware for 
the interbank move capability, and can use the 
zBO L D l R instruction for intrabank moves. 


? m o m set banks for one following ?MOVE 


?XIIDVE is called with the destination bank in 
register B and the source bank in register C. 
~nterbank moves are only invoked if the DPAs 
specify deblocking buffers in alternate banks. 
? M O V E only applies to one call to ?MOVE. 
( ~ o t 
implemented in the example.) 


?BANK Set bank for execution 


?BANK ie called with the bank address in 
register a. 
his bank address has already 


been stored in (CBNK for future reference. 
~ 1 1 
registers except A must be maintained upon 


return. 


=able 4-12. Y a e llodule Entry Points 


4.9 
Linking Mdules into the 610s 
- 


The following lines are examples of typical link conmclnds to 
build a modular BlOS ready for system generation with GENCPI: 
- 


- 


~ n d 
of Section 4 
- 


Section 5 
System Generation 


- 
This seotion describes the use of the GENCPM utility to create 
a memory image CPM3.SYS file containing the elements of the CP/M 3 
operating system. 
This section also descr~hes customizing the 


LDRBIOS portion of the CPMLDR program 
- 
to read the CPM3.SYS flle into medb:d 
the operation Of CPMLDR 
describes the procedure to follow to bm; Cfjp:.ly' 
section 


I" the nonbanced system. C M C P M creates the CPW~.SIS file €can 


the BWS3.SPR and your cuatomlred BIOS3.SPR file.. 
In the banled 
- 
SYStem. GL1ICPMCleates theCPH3.s~S frle from the ReSBDOS3.SPR flle. 
the BNKBWS3.SPR flle, and your cusromlred BUKBIOS3.SPR f ~ l e . 


If your 610s ~Ontaina a segment that can reside in banked 
memory, GMCPM separates the code and data in BNIBIOS~.SPR into a 
banked portion uhioh resldes in Bank 0 just below common memory, and 
a resident portion which resides ~n common memory. 


GENCPM relocates the systemmodules, and can allocate physical 


record buffers, allocation vectors 
checkgum vectors, and hash 


tables as requested in the BlOS data btructures. 
~t also relocates 
references to the system Control Block as described on page 27. 
GBNCPM acoepts its oomand input frdm a flle, GENCPM.DAT, or 
interactively from the console. 


5.1 
OBICP* utility 


Syntax; 


GENCPM IAUTO 
I AUTO D I S P ~ Y J 


Purgose; 


GENCPM creates a memory Image CPM3.SYS file, containing tbe 


CP/M 3 B W S and customized Blos. The G M C P M utility performs late 
resolution of inte~module references between aystem modules. GMCPM 
can accept its command input interaotively from the console or from 
a file GENCPM.DAT. 


In the nonbanked system, G M C P M create* a CPM~.SYS file from 
the BWS3.SPR and BIOS3.SPR files. 
In the banked system, GENCPn 


Creates the CPM3.SYS file from the RESBWSJ.SPR, the BNKBDOS3.SPR 
M d the B11KB10S3.9~~ 
files. Remember to back up your CPM3.SYS file 


, " ; ~ ~ , r ~ s e ; ~ ~ ~ t ~ ~ f s O r ~ ~ ~ ~ ~ e ~ e p ~ ~ ~ ~ s ~ 
,;yyytt$etea 
any exlrting 
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1 n ~ v t 
piles: 


~ a n k e d 
System 
sonbanked System 


Optionally GBNCPM.DAT 


output File: 


CPM3.SYS 


Optionally GEIICPM.DAT 


a m determines the location of the system modules in memory 
and, optionally. the number of physical record buffers allocated to 
the system. 
GENCPH can specify the location of hash Cables 
requested by the Disk Parameter Headers (DPHS) in the BIOS. GBNCPM 
can allocate all required disk buffer space and create all the 
required ~ u f f e r control m o c k s (BCBS). 
GENCPM can also create 


checksum vectocs and allocation vectors. 


r r ...... 
rh- srsm nr+~r.nv narimetrr in the oomand line. 


he GLNCPM.DIT file ha an ASCII fllc of variable names and 


theLr a560C~aCed values. 
1n rhc'tollalng 
dlsc~aslon, a varlable 


name in rhe GENCPH.DI\T flle Is referred t o as a Qlestlon Variable. 
I\ line ~n the GEWCPH.DIT tllc takes t>e follov~nq qeneral form 


Question Variable = value I ? I ?value <CRXLP> 


value = (decimal value 


or hexadecimal value 
or drive letter (A - Pl 


- 
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- 
YOU oan specify a default value by following s question mark 
with the appropriate value, for example ?A or ?25 or ?Y. 
he 


queation mark tells GENCPM to stop and p r m p t the veer for input. 
thencontinue automatically. At a ?value entry, GENCPM displays the 
default value and stops £0. 
verification. 


The following pages display GBNCPM questions. 
The items in 
parentheses are the default values. 
The Question Variable 


associated with the question is shown b e l a the explanation of the 
answers to the questions. 


Program ~uestions: 


Use GENCPM.DAT ffo defaults (Yl ? 


Bnter Y - GENCPM gets its default valves from the file 
GENCPM.DAT. 


Enter N - GENCPM uses the built-in default values. 


No Queation variable is asnaciated with this question 


Create a new GEIICPH.DAT file (w) ? 


Enter N - GENCPM does not create a new GENCPM.DAT fils 


Enter Y - After GENCPM generates the new CPU3.SYS file it 
creates a new GENCPI.DAT file containing the default 
values. 


Question Variable: 
CRDATAP 


Display Load Table at Cold ~ o o t 
( Y ) ? 


Bnter Y - On Cold Boot the system diaplaya the load table 
containing the filename, filetype, hex starting address, 
length of system modules, and the TPA size. 


Enter A - system displays only the TPA size on cold boot. 


Question variable: PRTnSG 


Number of console columns ((80) 7 


Enter the nulaber of columns (characters-per-line) for your 
console. 


A charaoter in the last column must not forse a new line 
For console editing in CP/M 3. 
If your terminal forces a 


new line autmatically, decrement the column count by one. 


Question Variable: 
PAWID 
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Number of lines per console page (1241 7 


Enter the number of the lines per screen for your console. 


Question Variable: 
PAGLEN 


Backapace echoes erased character IN) 7 


Enter N - Backspace (ctrl-R, 0 8 8 ) moves back one column and 
erases the previous character. 


Enter Y - Backspase moves forward one column and displays 
the previous character. 


Queation Variable: 
BICKsPC 


nubout echoes erased character (Y) 7 


Enter Y - Rubout (788) moves forward one column and 
displays the previous charaoter. 


Enter N - Rubout moves back one column and erases the 
p.e"i."B 
Character. 


Question variable: 
RUBOUT 


Initial default drive (A:) 7 


Entec the drive code the prompt is to display at cold boot. 


Question Variable: 
BWTDRV 


TOP page of memory (PPI 7 


Enter the page address that is to be the top of the 
operating system. OPPH is the top of a 64K (iyrten. 


Question Variable: 
m M m P 


Bank-switched memory ( Y ) 7 


Enter Y - GENCPM uses the banked system files. 


~ n t e r 
N - GBNCP" uses the nonbsnked system files. 


Question Variable: 
BNRSUT 


common memory base page (CO) 7 


his question is displayed only if you answered Y to the 
previous question. 
~ n t e r 
the page addresa of the s t a r t of 
common memory. 


Question variable: 
CONBAS 
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~ o n g 
error meesages (YI 7 


This question ia displayed only if you answered Y to hank- 
switched memory. 


Enter Y - CP/M 3 error messages contain the BDOS function 
number and the name of the file on which the operation war 
attempted. 


Enter N - CP/M 3 error messages do nor display the function 
number or file. 


Question variable: L E W R 


ooubie allocation vectors (Y) 7 


m i a question is displayed only if you answered a to bant- 
switohed memory. 
Por more infomatlon about double 


allocation vectors, see the definition o f the ~ i s k 
Parametec Reader ALV field in Section 3. 


Enter Y - GENCPM creates double-bit allocation vectors for 
each drive. 


Enter N - GENCPM creates single-bit allocation vectors for 
each drive. 


Question Variable: DBULV 


Accept new system definition ( Y l 7 


Enter Y - GENCPM proceeds to the next set of questions. 


Enter N - GENCPM repeats the previous questions and 
displays your previous input in the default parentheses. 
YO" can modify your answers. 


No Question Variable is associated with this question. 


Number of memory segments (131 7 


GBNCPM displays this question if you answered Y to bank- 
witched memory. 


Bncer the number of memory segments in the system. 
DO not 


oount cornon memory OI memory in Bank 1, the TPA bank 
memory segment. a maximum of 16 (O - 15) memory aedm2nst: 
are allowed. 
he memory segments define to GENCPH the 


memry available for buffer and hash table allocation. 
DO 


not include the part of Bank 0 that is reserved for the 
operating system. 
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~ n t e r 
memory segment table: 


~ase,sire.bank (OO.BE.00) 7 
Base,size,bank IOO,CO,OZl 7 
~ase.sire,bank (OO.CO.03) 7 


Enrer the base page, the length, and the bank of the memory 
segment. 


Question Variable: 
I(BllSEG01 where * = 0 to P hex 


accept new memory segment table entries (Yl ? 


m t e r Y - GENCPM displaya the next group of questions. 


Enter A - GENCPM displays the memory segment table 
definition questions again. 


NO Question variable is associated with this question. 


Setting up directory hash tables: 


Enable hashing for drive d: (Yl : 


GENCPM displays this question if there is a Drive Table and 
if the DPHs for a given drive have an OFrPEH in the hash 
table address eield of the OPE. he question is asked for 
every drive d: defined in the BIOS. 


Enter Y - Space is allocated for the Hash Table. 
The 
address and bank of the naah Table is entered into the DPA. 


Enter N - N O space is allocated for a "ash Table for that 
drive. 


Queaeion Variable: 
HRSRDRVd where d = drives A-P. 


setting up ~locking/~eblocking 
buffers: 


GENCPM displays the next set of questions if either or both 
the DTABCB field or the O I W C B field contain OPPFEH. 


Number of directory buffers for drive d: (Ill ? 10 


This question appears only if you are generating a banked 
system. ~ n t e r 
the number of directory buffers to allocate 
for the specified drive. 
In a banked system, directory 
buffers ere allocated only inside eank 0. 
1" a nonbanked 


system, one directory buffer is allocated above the BIOS. 


Question Variable: 
NolRRBCd where d - drives A-P. 


- 
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- 
Number of data buffers for drive d: 0 1 ) ? 1 


This question apptars only if you are generating a ~ a n k e d 
sy~tem. Enter the number of data buffers to allocate for 
the specifled drive. 
In a banked system, data bvffers can 


only be allocated outside Bank 1, and in common. You can 
only allocate data buffers in alternate banks if your BIOS 
8YPPOrtS interbank moves. 
1" a nonbanked System, data 
buffers are allocated a h w e the BIOS. 


Question Variable: 
NDTAREC~ where d = drives A-P. 


Share buffer(s1 rich which drive (A:) ? 


This question appears only if you answered zero to either 
of the above questions. 
Enter the drive letter (a-PI of 
the drive with which you rant this drive to share a buffer. 


Question Variable: 
ODIRDRV~ for directory records where d 
- drives A-P. 


Question Variable: 
ODTADRvd for data records where d = 


drives A-P. 


Allocate buffers outside of Commom IN1 ? 


This question appears if the BIOS XMOVE routine is 
implemented. 


answer Y - GBNCPN allooates data buffers outside of common 
and Bank 0. 


Answer N - GENCPM allocates data buffers in common. 


Question variable: 
ALTBNKSd where d = drives A-P. 


Overlay Directory buffer for drive d: (Y) ? 


This question appears only if you are generating a 
"onbanked system. 


Enter Y - this drive shares a directory buffer with another 
drive. 


Enter N - GENCPM allocates an additional directory buffer 
above the 810s. 


Question Variable: 
OVLYDIR~ rhere d = drives A-P. 


- 
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overlay ate buffer for drive d: (7) ? 


This question appears only if you are generating a 
"onbanked system. 


Enter Y - this drive shares a data buffer with another 
drive. 


Enter N - GENCPM allocates an additional data buffer above 
the BIOS. 


westion Variable: 
OVLYDTA~ for directory records where d 


= drlve8 A-P. 


Accept new buffer definitions ( Y ) 3 


Enter Y - GENCPM creates the CPM~.SYS file and terminates. 


E n t e r N - GENCPM redisplays all of the buffer definition 
questions. 


No Question variable is associated with this question. 


Exara~leS: 


=he follovina section contains examoles of t w o svsten 


qenezac~on S P L S L O ~ S . I I no e n t r y follows a progranqueatlon, asndne 
RPTURY 
was entered CO Erlecr Cne default value I n parentheses. 


~ n t r ~ e a 
d~ffecent from t h e default aporac afrer the qlest~on 
nacr. 


EXIV*PLE OF CONTENTS OF GEIICPM.DAT FILE 


conbas - cO <CR> 
lerrar = 7 <CR> 
nurnseas = 3 <CR> 


hashdrva - y <CR> 
hashdrvd = n <CR> 
ndlrreca = 20 <CR> 


E W L B OF SYSTEM GENERATION WITH BANKED +EMORY 


A I G E I X r n 


CP/M 3.0 System Generation 
Copyright (Cl 1982. Digital Research 


Default entries are shown in (parens). 
~efeult base is Hex, precede entry with + for decimal 


- 
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- 
Use GENCPM.DAT for defaults ( Y ) 7 


Create a new GENCPM.DAT file (N) 7 
- 
Display Load Map at Cold Boor (Y) 7 


Number of console columns ((80) 7 
Number of lines in Eonsole page (124) 7 
- 
Backspace echoes erased character IN) 7 
Rubout echoes erased character (N) 7 


Initial default drive (a:) 7 
- 
Top page of memory (PP) 7 
Bank switched memory ( Y ) 7 
Cornon memory base page (COB 7 
- 
Long error messages (Y) 7 


Accept new system definition (Yl 7 


.'* 
Bank 1 and cornon are noc included **' 
- 
*'* 
in the memory segment table. 
*.* 


Number of memory segments (13) 7 


- 
CP/M 3 Base.size,bank (88.35.00) 


Bnter memory segment table: 


Base,srze,bank (00.88.00) 7 
Base.rize,bank (00.B3.02) 7 
- 
Base.sire,bank (OO.CO.03) 7 


CP/M 3 Sys 
8B00R 3500A Bank 00 


Mernseg NO. 00 0 0 0 0 ~ 
BOOR Bank 00 


MemSe4 NO. 01 ODOOH BlOOR 
Bank 02 


Accept ne* memory segment table entries (Y) 7 
- 
Setting up directory hash tables: 
Enable hashing for drive a: ( Y ) 7 
Bnable hashing for drive 8: (Y) 7 
Enable hashing for drive C: (Y) 7 
- 


Enable hashing for drive D: ( Y ) 7 
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setting up ~locking/oeblocking buffers: 


The physical record size is 0200n: 


&vailahle space in 256 byte pages: 
TPA - 00F4H. Bank 0 - 00888, Other banks - 0166H 
- 


~unher of directory buffers for drive A: (1321 ? 


Available apace In 256 byte pages: 
- 


TPA = OOF4H. Bank 0 = 0049H. Other banks = 0166H 


Number of data buffers for drive A: 112) ? 
Allocate buffers outside of C m o n IN1 7 
- 


mailable apaoe in 256 byte pages: 
TPA = OOFOH. Bank 0 = 0049". Other banks 
0166R 


Number of directory buffers for drive 8: 032) ? - 


Available space in 256 byte pages: 
TPA i OOPOH, Bank 0 - 0007H. Other hanks 
0166H 


umber of data buffers for drive 8: (101 ? 
- 


share bufferls) with which drive (A:) 7 


he physical reoord size is 0080H: 
- 


Available space in 256 byte pages: 
TPI\ = OOPOH, Bank 0 - 0007H. Other banks 
0166H 


Number of directory bvffers for drive C: 1110) ? - 


~vallable space in 256 byte pages: 
TPS. - OOrOH, Bank 0 = 00018, Other banks = 0166R 


~unher of directory buffers for drive D: 110) ? - 
Share huffer(8) with which drive ICsI ? 


~vailable spaoe in 256 byte pages: 
T P ~ - 0010~. ~ a n k 
0 - 0001~. Other banks - 01668 
- 


~osept new buffer definitions IY) ? 


BNRB10S3 SPR F600H 0600R 
811RBIOS3 SPR BlOOR OFOOH 
RESBDOS3 SPR POOOH 06008 
BNXBOOS3 SPR 8700H 2hOOH 
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EXUlPLB OF SYSTEM GENERATION WIT8 NONBANLNWD MEMORY 


A>Gm3CPY 


CP/M 3.0 System Generation 
Copyright (C) 1982, Digital Research 


Default entries are shown in (parens). 
Default base is ex, precede entry with 1 for decimal 


use GENCPM.DAT for defaults ( Y ) ? 


Create a new GENCPM.DAT file IN) ? 


DiSplay Load Hap at Cold Boot (11 7 


Number of console columns (180) 7 
Number of lines in console page (124) 7 
Backspace echoes erased character IN) ? 
Rubout echoes eraaed character (Nl 7 


Initial default drive (A:) 
? 


TOP page of memory IFF) 7 
Bank switched memory (Y) 7 R 


Double allocation vectors (Y) 7 


Accept new aysten definition (Y) 7 


Setting up Blocking/Dehlocking buffers; 


The physical record sire is 02008: 


Available space in 256 byte pages: 
TPA 
00088 


*.* 
Direotory buffer required *** 
." 
and allocated for drive A: ... 


Available space in 256 byte pages: 
TPA . 
00058 


Overlay Data buffer for drive A: (Y) ? 


available space in 256 byte pages: 
TPA 5 00D5H 


Overlay ~irectory buffer for drive 8: 
( Y ) ? 


Share buffer(s) with which drive (A:) 
7 


available space in 256 byte pages: 
TPA - 00D58 
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O V F I ~ ~ Y 
Data buffer for drive 61 IYI 7 


Share buffer(e) rith whioh drive (A:) ? 


he 
record sire is 0080X: 


Available apace in 256 byte pages: 
TPA - 0005H 


Overlay Directory buffer for drive C: (Yl 7 
share buiferls) rith whioh drive (A:) ? 


Available space in 256 byte pages: 
TPA r 00D5R 


overlay ~irectory buffer for drive D: (Y) 7 
share bufferle) sith which drive IC:) ? 


hvailable space in 256 byte pages: 
TPA = 0005R 


~ c c e p t new buffer definitions (YI 7 


810.93 
SPR F3OOX OBOOH 


BOOS3 
SPR D600H lDOOR 


t 
' 
. 
CP/M 3.0 SYSTEM GBNEPATION DONE *** 


A> 


5.2 
Customizing the CPULDII 


he CPMLDR resides on the system tracks of a CP/M 3 system 
dink, and loads the CPH~.SYS file into lnenory to cold start the 
system. CPMLDR contains the LDRBDOS supplied by Digital Research, 
and must contain your customized LDRBIOS. 


be system tracks for CP/M 3 contain the oustonized Cold Start 
Loader, CPMLOR with the customized LDRBIOS, and possibly the CCP. 


he COPYSYS utility places the cold start Loader, the CPMLDR, 


and optionally the CCP on the system tracks, as shown in Table 5-1. 


- 
CP/M 3 s y s t e m ~ u i d e 
5.2 
c u s t o m i z i n g t h e CPIILDR 


T a b l e 5-1. 
S-ple 
CP/M 3 System T r a c k O r g a n i z a t i a n 
- 
r T r a c k I sector I p a g e I Memory A d d r e s s I CP/M 3 n o d u l e Name I 


00 
0 1 
B o o t A d d r e s s 
C o l d S t a r t Loader 


0 0 
0 2 
00 
OlOOH 
CPMLOR 


0 1 
26 
2 5 
1A00H 
CCP 


T y p i c a l l y t h e C o l d s t a r t Loader is l o a d e d i n t o memory from 
T r a c k 0 , S e c t o r 1 of t h e e y s t e m t r a c k s vhen t h e r e s e t b u t t o n i s 
d e p r e s s e d . 
The C o l d S t a r t Loader t h e n l o a d s CPMLDR from t h e s y s t e m 


traoks i n t o memory. 


A l t e r n a t i v e l y , i f you are s t a r t i n g from an e x i s t i n g CP/M 2 
system, you can run CPIILDR.COM as a t r a n s i e n t program. 
CP/M 2 l o a d s 


CPHLDR.COM i n t o memory a t l o c a t i o n 1008. 
CPMLDR t h e n r e a d s t h e 


CPMI.SYS 
f i l e from User 0 on d r i v e A a n d l o a d s it I n t o memory. 


Use t h e f o l l o w i n g p r o c e d u r e to o r e a t e a c u s t o m i z e d C P I I L D R . ~ 


f i l e , i n c l u d i n g your c u s t o m i z e d IDRBIOS: 


11 p r e p a r e a LDRBIOS.AS" 
f i l e . 


21 Assemble t h e LDRBIOS f i l e w i t h RMhC t o produce a LDFm10s.m~ 


f i l e . 


3) L i n k t h e s u p p l i e d C ~ I I L ~ ~ . m ~ 
f l l e r i t h t h e LDRBIOS.REL f i l e 


YOU c r e a t e d to produce a CPMLDR.COM 
f i l e . 


ArPmK cPam[LlOOI-CPmLm,LD.BI(15 


Replace t h e a d d r e s s 100 r i t h t h e l o a d a d d r e s s to which your 
h o o t l o a d e r l o a d s CPMLDR.COH. 
You must i n c l u d e a b i a s o f 


lOOH b y t e s f o r b v f f e r space vhen you d e t e r m i n e t h e l o a d 
a d d r e a s . 
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=he CPlllDR requires a customized LORBIOS to perform disk inpvt 


and console output. 
The LDRBIOS in essentially a nonbanked BIOS. 


he IORBIOS has the same JMP vector as the regular CP/M 3 810s. The 
LDRBIOS is called only to perform disk reads IREhO) from one drive, 
console output ICONOUTI for sign-on messages, and minimal system 
initialization. 
- 


he CPMLDR oalls the B W T entry point at the beginning of the 


LDRBIOS to allow it to perform any necessary hardware 
~n~tialization. The BWT entzy point should return to CPnLDR 
:K"*",i;",,.":;;;y;;;n."O;"di~bl~;h:." 
;p'gRB;"oy;z 
C 


routine is called. 


~ e s t 
your LORBIOS completely to ensure that it properly 


pecforms console character output and disk reads. Check that the - 
proper tracks and sectors are addressed on all reads and that data 
is transferred to the proper memory locations. 


YOU should assemble the loRBIOS.rsn file with a relocarable 
origin of OOOOR. 
~ssemble the LDRBIOS with m 
c 
to produoe a 


LDRBIOS.REL file. 
Link the LDRBIOS.REL file with the CPMLDR.REL 


file supplied by ~ i g i t a l 
~esearch 
to create a CPMLDR.COM file. Use 


the L option in LINK to specify the load origin (address) to which 
the bmt loader on track 0 sector 1 loads the CPHLDR.COM file. 


Unnecessary BIOS functions can be deleted from the LDRBIOS U, 


conserve space. =here is one absolute reskriction on the length of 
the LDRBIOS: it cannot extend above the base of the banked portion 
of CP/M 3. 
(GENCPH lists the base address of CP/M 3 In its load 


map.) 
If you plan to bmt CP/M 3 from standard, single-density, 
eight-inch floppy disks, your CPMLDR must not be longer than 1980A 
to place the CPMLDR.COM file on t w o system tracks with the boot 
sector. I€ the CCP resides on the system tracks with the Cold Start 
loader and C P ~ D R , 
the combined lengths must nor exceed 1980H. 


Synrar: 


CPMLDR 


Purp08ei 


c e m o n loads the CP/M 3 system file c e ~ 3 . s ~ ~ 
into ~ a n k 
0 and 
transfers control to the BWT routine in the customized 610s. You 
can specify in G M C P M for CPHLDR to display a load table containing - 


the names and addresses of the system modules. 


CP/M 3 System Guide 


I n m t File: 


CPU3.SYS 


axamp1es: 


A > C A a D P 
CP/M V3.0 Loader 
CoPYcight ICI 1982, Digital Research 


BNKBIOS3 SPR P600R OA008 
BNRBIOS3 SPR BBOOB 0500W 
ReSBWS3 SPR PlOOB 0500B 
BNKBWS3 SPR 9A00H 2100A 


60X TPA 


A, 


- - =.---.-..> 
-..-.---, ".. 
" - - r - " , m 
-.- 
..-u= 
02." 
"=rs.",, 


mnnber, the Digital Research copyright mesaage, and a four-oolmn 
load table oontaining the filensune, filetype, her starting address, 
and length of the system modules. 
CPMLDR caapletes its sign-on 


message by indicating the sire of the Transient Program Area (TPA) 
in kilobytes. 
The CCP then displays the system prmpt, A>. 


me CP/M 3 cold start operation loads the CCP, BWS, and BIOS 


modules into their proper lwations innenory and pasaes control to 
the cold start entry point (810s Function 0: 
BOOTI in the 810s 


Typically. a PROM-based loader initiates a cold atart by loading 
-tor 
0 on track 1 of the system tracks into n m o r y and jmping to 


it. 
This first sector contains the cold Start Loader. 
he cold 
Start Loader loads the CPMLDR.COM program into n m o r y and j m p s to 
it. 
CPMLDR loads the CPM3.SYS file into memory and j m p s to the 


BIOS cold start entry point. 
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To hoot the CP/M 3 system, use the following procedure: 


11 create the CPM~.SYS file. 


21 Copy the CPM3.SYS file to the hoot drive. 


31 Create a CPHLDR.COM for your machine. 


4 1 Place the CPMLDR.COM flle on your system tracks using SYSGEN 


with CP/M 2 or COPYSYS with CP/M 3. 
The hoot loader must 


place the CPMLDR.COH File at the address at which it 
orioinated. If CPWLDR has been linked to load a t lOOH, You 
can2run CPMLDR under CP/M 2. 


=he COPYSYS utility handles initialization of the system 


tracks. The source of COPYSYS is included vith the standard CP/M 3 
system because you need to customize COPVSYS to support nonstandard 
system disk formats. 
COPYSYS copies the cold Start Loader, the 


CPMLDR.COM file. and optionally the CCP to the system tracks. Refer 
to the COPYSYS.ASH source file on the distribution disk. 


~ n d 
of Section 5 


Section 6 
Debugging the BlOS 


his s e c t i o n d e s c r i b e s a sample debugging sesaion for a 
nonbanked CP/M 3 BIOS. 
You nuat c r e a t e and debug your nonbanked 


system f i r s t , then bring up the banked system. 
~ o t e 
t h a t your 


systemprobably displays addresses t h a t d i f f e r from the addresses i n 
t h e following example. 


YOU can use SID, ~ i g i t a l 
~ e s e a r c h ' s symbolic ~ e b u g g e r ~ r o g r a m , 


running under CP/M 2.2, t o help debug your customized BIOS. 
=he 


f o l l a r i n g s t e p s o u t l i n e a sample debugging session. 


11 Determine the amount of memory available t o CP/M 3 when the 
debugger and CP/M 2.2 are i n memory. 
To do t h i s , load the 
debugger under CP/M 2.2 and l i n t the jump i n e t r u c t ~ o n a t 
l m a t i o n 0005R. 
1n the following example of a 64R system, 


C500 i a the base address of the debugger, and a l s o the 
m a ~ i m ~ ~ . 
top Of memory t h a t you can specify i n OENCPH for 
your customized CP/M 3 system. 


A S I D 
CP/M 3 SID - Version 3.0 
IL5 
0005 
JUP 
C500 


21 Running under CP/M 2.2, 
use GENCPM to generate s c ~ n 3 . s ~ ~ 


f i l e , which s p e c i f i e s a top of memory t h a t i s l e e s than the 
base address of the debugger, as determined by the previous 
step. ~ l l a r 
a t l e a s t 256K bytes for a patch area. I" t h i s 
example, you can specify c3 t o GENCPM as t h e top of memory 
f o r your CP/M 3 system. 


Top page of memory ( m ) ? C3 


31 NOW you have created a system small enough t o debug under 


BID. 
UBe SID t o load the CPMLDR.COM f i l e , aa shown i n the 
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A>BID CRaDB.COII 
CP/M 3 SID - Vecsion 3 . 0 
NEXT MSZE PC END 
07380 OE80 0 1 0 0 D4FF 
+ 


4 ) use the I cornnand in SID as shorn in the next example, to 
place the charactere $B 'into locations 005DR and 005EH of 
the default PCB based a t 005CH. 
The $6 causes CPMLDR.COM 
to break after loading the c ~ t 4 3 . S Y S file into memory. 


5) ~ransfer control to C P ~ D R 
using the G c-and: 


10 


at this point, the screen cleats and the folloring 
information appears: 


CP/M 
V 3 . 0 LOADER 


copyright (c) 1982, Digital Research 


B 1 0 S 3 
SPR MOO 
OBOO 


8 0 0 5 3 
SPR 8 8 0 0 
lFOO 


34K 
TPA 
. 
01A9 
* 


- 
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The Output frol your 6106 night look like this: 


JMP AA68 
JHP M B E 
JMP ABA4 
JHP ?.8AF 
JMP ABCI 


7) Now set a passpoint in the Cold BOOT routine. 
Use the P 


-and 
with an addre88 to set a passpoint at that address. 


IPM68 


81 Continue with the CPIILDR.COM program by entering the o 


command, followed by the address of Cold B m t , the first 
entry in the 810s j m p vector. 


IGMOO 


9 ) ID response to the G camand, the CPMLDR transfers control 
to the CP/M 3 operating system. 
If you set a passpoint in 
the Cold B W T routine, the program stops executing, control 
transfers to SID. and you can begin tracing the B W T 
routine. 


10) When you know the BOOT routine is functioning correctly, 
enter Passpoints for the other routines you want to trace 
and begin tracing step by step to determine the location og 
problems. 


~ e f e r 
to the ~igitsl Research S bolic Instruction ~ebuqqer 


users* Guide (SID) in the P r o q r m e r T u t i l i t i e s Guide for the cp/n 
Fanilv of Operatinq Systems for a discussion of all the SID 
cannands. 


Bnd of Section 6 


Appendix A 
Removable Media Considerations 


- 


All disk drives under CP/M 3 are olassified as either permanent 


01 removable. In general, removable driver support media changes. 
permanent drlves do not. 
Setting the high-order bit zn the CK; 
- 
Eleld 10 a drive's Disk Parameter Block IDPB) marks the drive as a 
permanent drive. 


The BDOS flle system distinguishes between permanent and 
removable drives. If a drlve is permanent 
the BOOS always accepts 
- 
the contents of physical record buffers a; 
velld. 
rn addxtlon, it 
a i s ~ 
accepts the results of hash table searches on the drive. 


on removable 


mre complicated. 
B W S nuer discard < 
related B W S fun< 
detect. nedia than 
directory record, 
-pares 
the check 


checksum vector. 
assumes the media 
medl 


drlves, the 8tatu8 Of physical record buffers is 
Because of the potential for media change the 


lirectory buffers before performing nost directory 
:tion calls. 
This is requlred because the BWS 


ges by readlng directory records. When ~t reads a 
the BDOS computes a checksum for the record, and 
:sum to the cucrently stored value in the drivena 


If the checksum values do not match, the BDOS 
has charmed. 
Thus. the Boos ran onlv detect a 
a change by an actual directory GAD 
operation: -..-' - 
- 
A s~rnilar situation OCCUTS ~ l t h 
directory hashrng on removable 
drives. 
Because the directory hash table is a memory-resident 
table, the B W S must verify all unsuccessful hash table searches on 
removable drives by accessing the dlrectory. 


The net result of these actions 1s that there is a significant 
Performance Penalty associated with removable drlves as compared to 


only detected durlng directory operations. If the media 1s changed 
On a drlve during B W S WRITE operations, the new disk can be 
damaged. 


The BIOS media flag facility gives you another option for 
supporting drlves with removable media. 
However 
to use this 
option, the disk controller must be capable of 'generating an 
interrupt when the drlve door is opened. If your hardware provides 
thlS Support, YOU Can ImPIOYe the handllng of removable media by 
implementing the following procedure: 


11 nark the drive as a permanent drive and set the DPB CKS 
- 
parameter to the total number of directory entries, divided 
b~~F~u[;~~fy~~;y~;~$ 8y1sHt,he CKS fleld for a d ~ s k 
with 96 
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~ 
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l 
e 
~ e d i a 
considerations - 


2) ~ ~ p l e m e n t 
an interrupt service routine that sets the @MEDIA 


flag in the System Control Block and the DPH MEDIA byte for , 
*he drive that signaled the door open condition. 


~y using the media flag facility, you gain the performance 
advantage associated with permanent drives on drives that support 
removable media. 
=he B 
~ 
S 
checks the System C o n ~ r o l Block @MEDIA 


operations on the drive. rn addition, lt temporarily classlfler any 
permanent disk with the DPH MEDIA flag set as a removable drive. 
zy;et",',z;'o";:;,"; ;: ,";;&ct;-: 
;;yey;;=;;d '$,'d,'dJ,",";nt: 


access the diak. 


ieorn f16g i; set, disk integrity is enhanced. 


~ n d 
of Appendix A 


Appendix B 
Auto-density Support 


auto-density support refers to the capability of CP/H 3 to 


support different types of media on a single drive. 
For example, 


m e floppy-dlsk dcives accept nlngle-sided and douhle-sided d ~ s k s 
in both aingle-denslty and double-denslty formats. 
Auto-denslty 


Support requires that the B I O S be able t o determine *he current 
density when SELOSK is called and to subsequently he able to detect 
a change in disk format when the READ or WRITE routines are called. 


m support multiple disk formats, the drlve's B I D S driver must 


include a m n k ~arameter m o c k IDPB) for each type of disk or 
include code to generate the proper DPB parameters dynamically. I" 
addition, the 6 1 0 s drxver must deteralne the proper format of the 
dlsk when the SELDSK entry point is called with register E bit 0 
equal to 0 ( i n ~ r ~ a l 
SBLDSK calls). 
I£ 
the BIOS driver cannot 
determine the format. ~t can return OOOOH in register pair HL to 
indlcete the select was not successful. Otherwise, it must update 
the ~ i s k 
parameter ~ e a d e r (DPB) to address a DPB that descr~hes 
the 
current media, and return the addresa of the DPH to the BOOS. 
- 
-: 
all subsequent SELDSK calls with register E hit 0 equal to I, 


the B I O S driver must continue to return the addresa of the DPH 
returned ~n the initial SELDSK call. 
The value OOOOH is only a 
legal return value for Initial SELDSK calls. 


After a driver's SELOSK routine has determined the format of a 
disk, the drlver's READ and WRITE routines assume thls 1s the 
correct format until an error LS detected. 
I£ an error is detected 
and the driver determines rhat the media has been changed to another 
format, it must return the valve OFPH in register A and set the 
media flag ~n the system control lock. =his s ~ g n a l s 
the BOOS that 


the media has changed and the n e x t B l O S call to the drive will he an 
initial SELOSK call. Do not modlfY the drive's DPH or DPB until the 
initial SELDSK call 1s made. N o t e that the BDOS can detect a change 
In media and will make an lnitlal SELOSR call, even though the B I O S 
RBAD and WRITE routines have not detected a disk format change. 
However, the SELDSK routine must always determine the format on 
initial calls. 
- 


A drive's oirk Parameter Header IDPHI 
has associated with it 
several uninlriallred data areas: 
the allocation vector, the 
checksum vector, 
the d~rectory hash table, and physical record 
- 
buffers. 
The size of these areas is determined by DPB parameters. 


I€ apace for these areas 1s explic~tly allocated in the B I O S , the 
DPB that requires the most space determines the amunt of menorv to 
allocate. 
If the BIos deiera the allocation of these area; to 


GENCPM, the DPH must be ~ n ~ t i a l l z e d 
to the DPB with the largest 
- 
apace reymlrements. 
I€ one DPB 2 % not largest in all of the above 
categories, a false one must he constructed so rhat GMCPM allocates 
suff~cient space for each data area. 
- 
End of Appendix B 


Appendix C 
Modifying a CP/M 2 BlOS 


- 
If you are modifying an exist~ng CP/M 2.2 8108, you must note 


the follaring changes. 


- . 
The 310s j m p vector is expanded iron 17 entry points in CP/M 
2.2 
to 33 entry points in CP/M 3. 
You must implement the 


necessary additional routines. 
- 
. 
The Disk parameter Header and Disk parmeter Block data 
structures are expanded. 


see section 3 of this manual, "CP/M 
3 BIOS Functional 
- 
Specifications." far details of the BIOS data structures and 
subroutines. 
The following table shows all CP/M 3 BlOS functions 


with the changes necessary to support CP/M 3. 
- 
Table C-1. 
CPhI 3 B I M Punctions 


Function 
Meaning 


BIOS Function 00: 
BM)T 


The address for the JHP at location 5 must 
be obtained f r m @MxTPA in the System 
Control look. 


SIOS Function 01: 
WBCOT 


The address for the JHP at lmation 5 must 
be obtained €ran @MXTPA in the System 
Control Block. 
The CCP can he reloaded 


f r m a file. 


BIOS Function 02: 
CONST 


Can be implemented unchanged. 


310s Function 0 3 : 
CONIN 


Can be implemented unchanged. Do not mask 
the high-order bit. 


Function 
Meaning 


BIOS Function 04: CONOUT 


Can be implemented unohanged. 


BlOS Function 05: 
LIST 


Can be Implemented unchanged. 


810s unction 06: AUXWT 


C a l l e d P U N C H in CP/M 2. 
C a n be 


mmpleaented unchanged. 


BIOS Function 07: 
AUXIN 


Called READER in CP/M 2. 
C a n be 
implemented unchanged. 
Do not mask the 
high-order bit. 


810s Function 08: 
H M E 


No change. 


BIOS FunOtion 09: 
SELDSK 


Can nor return a select error when SELDSK 
is called with b ~ t 
0 in register E equal 
to 1. 


BIOS Function 10: SETTRK 


NO change. 


BIOS runction 11: SETSEC 


sectors are physical sectors, not logical 
128-byte sectors. 


BIOS Function 12: 
SETDMA 


Nor called €or every READ or WRITB 
operation. 
a he DMA buffer can now be 
greater than 128 bytes. 
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Table C-1. 
(continued) 


mnceion 
~eaning 


BIOS Function 13: 
READ 


READ operations are in terms of physical 
sectozs. 
READ can return a OFPH error 
code if it detects that the disk format 
has changed. 


BIOS Function 14: WRITE 


WRITE operations are in terns of physioal 
sectors. 
1f write detects that the dlsk 


is Read-only, it can return error code 2. 
WRITE can return a OFFH error code rf It 
detects that the disk format has changed. 


BIOS FUnctlOn 15: 
LISTST 


Can be mplenented unchanged. 


BIOS Function 16: 
SECTRN 


Sectors are physical sectors, not logical 
128-byte sectors. 


The following 1s a list of new 610s functions: 


BIOS Function 17: CONOST 


BIOS FunCtlan 18: AUXTST 


BIOS Function 19: AUXOST 


BIOS Function 20: DEVTBL 


BlOS PunCti-n 21: 
D N l N l 


BIOS Function 22: DRVTBL 


BlOS F~notion 23: m L T I O 


BlOS Function 24: 
rLUSH 


610.5 Fvnctlon 25: MOVE 


BIOS Function 26: 
TIHE 
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BIOS Function 27: 
SELHE~ 


BIOS Function 28: SETBNR 


BIOS Function 29: XHOVE 


BIOS Function 30: USERF 


BIOS Function 31: 
RESERVl 


BlOS Bunction 32: RESERYZ 


End of Appendix C 
- 


Appendix D 


CPM3.SYS File Format 


=able D-1. c m 3 . s ~ ~ 
File m r m a t 


~ e c o r d 
contents 


Header Record (128 bytes) 
Print ~ e c o r d (128 bytes) 


reverse order, top do*". 


Table D-2. 
Reader aemrd Definition 


- 
The Print Record is the CP/M 3 Load Table in ASCII, 
terminated by a dollar sign ($1. 


- 
End of Appendix D 


~ y t e 
contents 


0 
TOP page plus one, at which the resident 
portion of CP/M 3 is to be loaded top dorm. 


1 
Length in pages (256 bytes] of the resident 
portion of CP/M 3. 


2 
TOP page plus one, at which the banked portion 
of CP/M 3 is to be loaded Cop down. 


3 
length in pages (256 bytes) of the banked 
portion of CP/M 3. 


4-5 
~ d d r e a s 
of CP/M 3 cold B 
~ 
C 
entry point. 


6-15 
Reserved. 


16-51 
Copycight Message 


52 
Reserved. 


53-58 
Serial Number. 


59-127 
Reserved. 


Appendix E 
Root Module of Relocatable BlOS for CP/M 3 


A l l the l i a t i n g s i n Appendixes E through I are assembled with 
m, theCP/nRelosatingMacroAaaabler. andcross-rcferencedrith 
M(EP- , an assembly languagecross-referenceprogrw used with m c . 
Theee l i s t i n g s are output f r m the XREP program. 
The assembly 


language sources are on your distribvtion disk as .ASM f i l e s . 


, I".. .. I.. ,.,..... 
I 
&, I.. .A__., 
11.1 ."I .. 
, 
d..L,.W..d.. .-.<:. 
( 0 % ,.IOI..LIrn.I 
",lrn... 
* . I 


&.I a..,..,-., 
,... .-. 
..&_., 
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.ddl"* 
"< 
."..i,"e 
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.La_,.. 
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.I,_. *.. 
<."* .... ",.,,. 1 0 - _... 
La.% 


<." 
n l.ll,".l .. .,-,, . 
.,.I.. 
, 
.."lle .,..,. 


, "..'.bL.. 
/. .".<.. 
d.*. 
-9s 


="ern ~~~".~,,~,".~,~.O"~~,~.~"~~,~,~"~~ , 110 csair*ct,m "*cto.* 
..ern 
,..rp 


*"ern 
*b"*bC 


/ .adr 
.*.L(. 
*"el" 
-,.t 
; 111 4" .C'.tlh 
bullr< 


> ,"%r,.L,*.t,m 


..%." 
,,"It 


="L." 
l L d c c ~ . l r l - ~ 
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..Le.d 
E C I I.. 
.-I . 
mCm 


, "... 
d.t,"d 
oh...er.r 
,,o 
r-"k,"-. 


. 
. 
l 
. 
" 
Ill .,..., 
.L.r_l.D.I 
; ... 
1 L.L. 
2. 
'aI 


*.tC" 
,C,",k 


<.kc" 
e*tbL 
, ,II,%.LfL.II.I 
dl"<.. 
L. 
'C. 
, pnY.?..i 
FD.r.rt*. 
d..lC, 
tab,< 


, dl.. 
.O."""l..tl- 
d.(. 
il."S 


."k." 
Wth, 
: *.MI 
wl.tl.. 
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P " * L L C I O .... 
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.. 
.. .. .. 
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Listing a-1. 
lmot mdule of Relocatable BIOS for CP/M 3 
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PYbLIC Icbnl 
sjlm 
I.Ds..,na". 


/ C"....L 
b..* 


*=LC" ,ao"& 


/ ..I<<L 
D"1 b."l. 
."d 
hLos* nay- 


/ .II.CL 
CI" &", 
, =la* 
.u*rt 


*ztc" ,L,"* 
; .Iq"., 
r,.. 
D P r l f l O " 


/ g*n*c.L 
"rlllry 


wlL.c 
,p..T,lO.~ . P.I"L .* ...... 
"""b.. 
<con O ta I 5 I l l 
."TrllL l*... 
, 
.,or 
dl.. 
rr.ar r .... 
* hc.drr 


..*lib 
LI..b."d 
, d*CL". 
D O . 
bit. 


: z.r*jn.l ".". 
Lor *I_ 
."err s l l r . 


*"bLIC 
, ~ I . , . m L . ? * m . ~ , 2 = ~ " , " , , c ~ " o , ? ~ ~ s ~ , ? . " = ~ . ~ a " = ~ 


PYLIi. IhD. ..,., 
dll,,.fri*,l.l....l.fd...l.*~a,7".ik. 


PY*LlC III.L..ISFL.. 
PYL1x. ..,. 
""I..leYID.,,~"Lb,.1d~"ln.1dit~1 
PY*ll. 
l.ll10,1fl".h.11C,l~,~,7~".m~,?s~h"t.~.~" 


, .IQP 
I_P rrFYI'. 


/ -11 DIoJ 
I.YL 
I... 
.re 
L..DkI* 
by .. 
.,in. 
fhl.C 
, 
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,: ,000 c,.... 
,-*: 
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on -la 
.tart 
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, r.mtir 
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9. 
ooos e m a , 
IC.".C. 
lop .o..' 
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0.l. 
c,trao 
,*."-, 
jnp ha. 
, 
d,.l. 
(0 Iol1C.l 
b a r 


l o 2 
.ols r,,roo 
,.Ld.i. 
jn0 ..ld.l 
, ..I. 
ck dl., 
dil.*. 
..turn dl., 
P...Yt.. 
Infa 


10, 
.a,. 
C 1 7 1 D O 
1.Lr.k: 
,nn .-ttr* 
, ..L 
I1.L 
L.... 


Lo. 
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119 
oo.5 c,cno. 
,nLrlai jW e.,rr. 
, 
nuLrln, 
'd 
car dl.* 
./O 


LIO 
no.. 
C,Cll0 
,L1".bl 
j.? 
flush 
, I,".h 
810s ..i"l.i"td 
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8 
arin.rmrxt 
. i t ""ll. no 


15, 
002, =3 


154 
0022 en 
PY.n 
n 
"Cnq 
. .."I 
(161" -inklr 
, "DP" aaaces, 1" '"G, 


155 
OOll 2~lelSllzB 
dC" h I do. 
)I I ._ .,. I t l 8.O.Y 
, ..c 
..lati*. 
d.L"* 


5 
2 
0 
..= 
I *t. r u l u 


157 
002D 2s 
or. h 
; 
.bIIIYt. 
<.dl 


158 
002E ,62B5= 
"01 0,. 
1 dC" I I .," 
*.II 
mlnr n l"il 
P-intrr 


15.) 
OOll ISCOBLO, 
"=b. , ..LL 
LCD, 
sjt '.,t polnlr. 


,so 
a o , ~ 8, 
P-P n 
. 
I".* 
re"t."s 


L6, 
ds%",t$"s"k. 
, ceoo"*. 
td."P-,"te, 


,6> 
ao>s c, 
P-P b 
, rlrs**r 
-Ync.r 
*"d arir. , 


1 6 1 
OOli X O I C l l i l l O 
l n i c I d ~ r 
I I In. dSl"iLllc+~ 
. and LmP ter saCII dl%". 
!'! no,c c,c,ao 
UDtl, 
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24, 
2.2 
2.3 
00x9 0600 
o"t*.e.": 


2.4 
co'".z<: 


."I 
b.0 
/ .t..l 
..el 
dl"%=. 0 


24, 
00- 
2. 


x.c 
0D.E D m 0 0 


d.d . 
. h M l -"t "."f 
- L C 


2.7 
OOE, E3 


I.= 
MLloUrId.rlC* 


2.8 
oar0 c5 


PY.lI h 
/ ..". 
LI. "=em1 


2.3 


-.ll 
b 
/ .."* 
Fw"l 
."< 
LI.r.c_c 


n.r$oull.*.dY. 
.I. 
0O.L 
CD2C.ID1"" 
r.11 
C0.L.. 
I .c.. 
< 3. .0r8oulli..dl 


25, 
oar8 "LC5 


z52 
oar* Cc4000 


wp b I *".h . , ... 
t..l 
and I 
. 
. 
. 
*. 
Ih. 
Cb....L.. 
.ld 
* l " l C I 


z5, 
00,D 
CL 


o.II 
, ,l d."k< 
.*,eor.a. 
pccne I t 


e5. 
*arc I, 


b 
, <l.O"., 
C(I".I ."a 
Sh...Cke. 


>s5 


)I 
, I.S.YI. 
LI. ... 
t st L h l "..Lor 


256 
oo,, 
0. 


nor$ourl*~rior: 


257 
0,OO 
7cx5 
" 
b 
/ *.r 
""*llC 


Z l l 
0102 E2I.OO 


ID" 
.,n 
I -.. 
L / .*1 11 ..r 
d.VlC1. 
L.fl 


259 
a105 <3 
,". 
os$nl"f 
/ -0 
q0 l,"d rn."... 


*.a 


.*t 


26. 
262 
ze, 
, commsr 


2*4 
, _ ..-1. 
. " I " L 
.I.t".. 
Y I Y . . 
I.". if 


2 6 5 


.I, 
..Ll.C.d 
.O"l.ll 
=".PI d*"lC.. 


Z $ & 
... 
.*.dl 


2.7 
2.8 
0106 2&*000 
=-"-.kZ 


>', 
0109 C,1101 


Lb.0 
erovrc 
, 
ron.ol. 
ournur b i t " . r ~ c 


270 
lSr 
O.t..=.. 


2 3 1 
272 
27, 
; m 
m 


2,. 


; 
L" .,,I., 
I wrwr Sk.tU.. 
".turn 
true Lt 


27s 


.I, 
.=I. 
.tea 
.".ill.C~ 
N t W L d."lCI. 


276 


.cI 
j..Oy. 


277 
278 
OLOC ZAoaOo 
.""ask 


27, 
OLD? CIIIOI 


lhld l.O".C , .lf .". 
."LWf 
bLr "..t.. 


ma 


,.P 
D.'I.r.n 


28. 
zrx 
283 
, L L n s l 


284 


/ 
L,.. 
O Y I Y L If.t".. 
Itl"." t.". if 


z a s 
.,, 
11.t 
w L W I 61"1... 


2#6 


.c. 


28, 
288 
01x2 ~ 
~ 
0 
0 
~ 
0 


,,Bt**: 


>a3 


LhlO e 
l 
. 
" 
. 
. 
, ..< 
,.*I 
WfWC bit "*OfOC 


290 
29, 
0x11 0600 
oe**ec.o: 


292 


."I 
b,O 
/ .f.cr "1Ib d*"l_ 
0 


29, 
o,,, 
2. 


cs.$"="t: 


294 
0.18 
E3 


*.d 
II 
, Ch.C* 
"."L 
bLf 


zqs 
01.9 
cs 


*".b 
h 
, ..** 
m. 
"*CtOC 


Z36 
a,,& ,=,, 


pY.n 
b 
: .."I 
r h l S-n* 


as, 
OllC rnlCO1 
.I, ..Or.l 
, 
0. "... 
.(.d" 


2.8 
a.,F 
c, 


5c 50.1=. 
, 
.L.I". 
thi. 
dell=. 


239 
a120 B, 


wP b 
, .*co"e. 
SOY"f 


IOU 
DL21 .l 


30, 
OL22 c. 
" : 
: ::z?a:k:c:*::::7 


>02 
OL2, 
0% 
, ,, 
_t 11.61. 
r(f"ln I.,.= 


303 
0.2. 
7cn5 


30, 
OL2* cz170, 
d': :., , ... * : :::',:':':'."%* 
-... .. a..,... 


30, 
DL29 ,SF? 
,". 
ro.lnnr 


306 
0128 c9 


0.m 
/ .I, ..,..Lid "I.. .1.dl. 
C.IY." 
(.Ye 


rst 


,a, 
~ i s t i n g 
&1. 
(continued) 


- 
CP/M 3 System Guide 
E R w t nodule of Relocatable 810s 


>08 
,m 
c-strri 
i nlrr. tor ournut asrio* -.ar. 
,".,"din. 
.prlon.l 


>,a 
OlZC &*2800 
, 
.on/rotl 
."*W.l 
- 
>l. 
m2, 
ES 
-1 
1.h I ."I 
D . O 
/ 
d."IC. 
_de I6 b,f. 


3L2 
0130 292929 


PY.h h 
; ..** 
Lr 1" .t.CL 


4.a 
1 
1 
0.d 
I s d l d l , 0.l.f. 
all..I 
I.tD 1."1.. 
.I.,aCL.r,,tl.. 
ml 


1L1 
0111 11"001)1 
1". d.ICLb,*6 , dad d , .'L. 
.d.,... 
of lodr Wfr 


o,,, 
7EZ$.O 


>.5 
O,,A 
EL 


.O" .,. 
I .", 
"b$.On.O1f 


,.6 
OX,& 
C ~ O ~ O O 
POP 1 
1. rr0.t 
, r*<e".. 
"".h*' ," 
<RL> 


/ n-r . 
=on d*",C*. 
rje Il.t 
DYIPYL .fatY. d 
L 
111 
0 1 3 1 L1IaD>I3 
1.1 
d..octll.r 
I d.d 
d , ".k' 
.oink.i 
la 
ernpi la/..ff 
fl.. 
- 
318 
0.42 
cD50a. 
wrmt, 
/ .1* 'f I>,. 
I.rhO.ja 
h.. 
.b...FtI. 


119 
O I 4 I 7ZE4LrOI 
"01 a.m 
1 0". cLI 
0 c Isad tey 1s snr 


1 2 0 
0149 rrllC21001 
cpl rrlq I lnz 
? 
ir. 
c r l - ~ . 


32, 
0l.Z 
, E m 


,22 
-", 
.,O"h 
/ 
Lb* *Laq 


111 
0150 rsllC11701 
rpl crls l lnl 
i l c its . 
rfl-l. 


$24 
0155 ,so0 
- 
325 


..I 
.,Doh 
: 
=,lar (DS flag 


,a' 
0.57 
2, 


32, 
0,5# CDCsa. 
"0" -,. 
c.., 
cost, 
/ .I"- 
en. 
f U 9 


128 
0158 8 8 
.". . 
s 9.f 
t h l .O(Y.l 
0 " I I Y L .L.(".. 


323 
a,% 
c* 
rek 
: am* I.., 
.Lth cLlii,..l-8 
*leg 


330 
; .ern." 
Lhi. .. 
Lb. 
.L.L". 


3,. 
- 
311 
0,s. 
C5.I 
<,.t,: 


PY.D 
h , -.n 
h 


/ 9-r Inwf .t.*"I .ill <.C. ."d 
.IS. 
..".d 


3>3 
@,5, 
maooa 


13, 
0162 B>C, 


>,5 
016. B, 
s* 
n l D 
W 
b 


>,# 
0163 c3 


-ra . 
,,, 
.=t 
- 
318 
339 
0266 "5S5 


CSSk,. 


PY.h 
b 1 
n , 9.t 
O Y t P Y t .t.fY., 
..",". 
<%I . 
'Xi. 


3.0 
01m C D ~ O ~ O 


,.I 
OLSB ELC. 
ca,, 
,-osc 


3.2 
0,m n, 
s P )I I D P b 
,., 0.6E 
"9 
oza a 


>a. 
r*t 
- 
3.3 
3.6 
ale, "3Z5 
=,,: 


W.l 
b I -".I )I . q I I 1"P"r. .W,IXI 
<.CI . 
IUL, 


3.7 
017, c~oooo 


34s 
01,. 
Em. 
ca,, 
2-, 


3.3 
0176 c9 
P - n h l r n b 


,,o 
re* 


,5, 
- 
352 
,5, 
, =ma2 


35. 


/ 
ED".Ol* 
InsY( I(.L".. 
%*t".. I.". i t 


355 
."Y 
..ISCt.d 
SD".Ol* 
jnpyc d."tC. 


>5< 


b.. 
a"a,,ab,* 
ohac.=t*,. 


35, 
I 5 l 
0117 >LOB00 
oonet, 
- 
>,9 
017% C,8*0, 
l h l d l.lV.0 
? see ran..,. '"Fur 
b i t "rrtor 


,6# 
I.r8.C." 


36, 
362 
36, 
, A"r.8, 


36. 
i 
U.111.r" 
l " W f SL.(".. 
.IfY." 
L."* 
<I 


3 6 5 


."Y .. 
.lored 
l n s k 
deliC1 
- 
,6< 
-" ."a,,ab.* 
=D .c.o t*,. 


36, 
360 
0170 110000 
a""xsc. 


,a9 


l h l d (I111.c 
; .st .". 
Inwe 1.l 


370 
,?I 
0L.O 
moo 
,st$.s.": 
- 
,,a 


111 b,O 
, .tact "In1 6.",11 
O 


37, 
0.82 
29 


0,*8"*.k, 


37. 
018, ,Em 
d.I II 
/ =h.rS ... 
L hLr 


>,r 
018, K l D O l 
.*% .,o 
/ 
dellCI "*L r..dr 


376 
a,.* 
a7co 


OC C'.LL 
/ I I * C L .t.L". 
LO. 
fhj. 
dellC. 


37, 
a,#* 
04 
era . 
I C", 
, ,I 
c..dl, 
rllYr" 
LrYI 


>7. 
0,m 7CB3 


.n. 
b 
, "."( 
d."IC1 
"" .... 
_ 
319 
0.m "18201 


.0" 
s.1 
1 or. 
L 3 ..I L f ."" 
mr* ..,.=L.d 


380 
0190 AP 
,". 
O..@"*"k 


u., c9 
".. . 
, ..I 
.I1.CL.I 
.I.. "-L ... 
0". 
,l*Yr. 
f .,.. 


3#> 
,#, 3s. 
385 
, c a m 
- 
181 


/ 
con.*,. 
,"out. 
IIIY." 
.".,.CI.I 
ern. 


38, 
j..dl 
lnPYL 4." i... 


3.8 
,*9 
0>*2 2*0000 
canin. 


390 
0,*5 c,mo, 
.b,O 
ec,"*- 
,"Z Ln?.s.. 
- 
Listing 1-1. 
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oca . 
j.. 
.it.d" 
, kh,. 
drrlc. 
n.. . 
ch.r.Lrrr 


a=. L 
/ -La., 
nlxk d..LCI 
- 
..h 
I oc. 
L / ..c 
11 ."Y 
-.= 
d*"LC1. 


I". rlln..t 
: 
l l P k .r tnc. 


;"$.*a" 
' "'"".' 
" """"' 


/ 
L,, 
(,"a . 
m.rrtrr 


F,Irdr: 


h 
, dl.o..a 
..era 
.t_I 
I.* 9Cl 


.20 
42, 


/ 
YtLLLI" 8Yh.DYII... 


.zz 
- 


.z, 
42. 
O D 6 z9 
,PD, 
, "eots.*d 
ChLL m%"t 


42, 


PChl 


.IS 
42, 
.,a 
Ip.-: 
, ?.."l 
"..I.g( 
I.*LI 
up to . 
""1. 


4 2 9 
O I B ? c5 
b , .o".. 
'=I . 
~ O % , 
- 


.,a 
OlS8 n5 


.,I 


r"/ln a 


P.98LDO. 


( 1 1 
Yla, 
lCB,CIC.OI 
n- .." 
I o.. . 
I J. 
P..9ll"lt 


a,, 
OlBC .re, 
=.. 
I 
h 


.I# 
OLCO CIIOCIIYE, 
-all ,5011) 
% P). h 
.,i 
ole. 2,c*aroi 
I"" n 8 i"? pm.lqrl-o 


.,s 
p".91*",L 
- 


4 x 7 
OLC. 
D l 


.,a 
OLC3 c, 


P P d 


433 
OLC& 


P P I 


a.0 


.=k 


a.1 
,DSC. 
. I'..f 
"""b.. 
0.6Illi 
c . a <xi, 


OLC8 0,.301,1,0 
1.L 
b.I.bL.LO1 
L., 
~,-lDooo 


.a, 
- 


a*. 
0,OL ,*2r 


# a > 
arc> 


""I 
..lo.-, 


.IY,...D. 
~ 
. 
h 
hl 1". .I 
d.d 
dl jnr .toploop 


4.7 
0 
, 
I 
I". 
SP1 in. 
.PI 
,"P 
pdrrl 


d.8 
.a9 
a,n= D%3 
sk*v,-e: 


?".h 
dl w.h 
h 
- 


( 5 0 
O I I n 4rCOOC00 
.D" *..I 
0.1, 
1 
. 
D 
. 
. 


.3. 
am. CLD, 


45z 


P)P b l PeV d 
nr.rd,qlri 


45, 
o m 6 s, 


4 5 4 
otn7 0"5WO> 
a 0 h 


455 
OLE% OA570, 


La1" bI .," 
*..I 
I". 
b 


loa. b& "0" d,.& ,". 
b 


43s 
olro iss2c2oto. 
..*, or. a, 3". 
nr.r 
- 


45, 
OLP2 c9 


4 5 E 


c c k 


459 
t*bL*,O 


4.O 
0 l , , , a.cecrrrs 
a" 
-IoOo.-IOo.-LO.-L(D 


461 
482 
lD.li. 


.I, 
nlro 2lDLOEOBI 
1.1 
11.6.1"11..q 
8 C.LI 
1P.q 
: l..Oc 
>..d.. 
- 


46' 
020, ,lrD(mC..L 
I.. 
l..," , .., ... 
I 
I ..LL 
>.O.D 
i dfl"l .Odl 


5 
0 
3 
L., 
n.tl.C*I.I. 
I =.LL 
9om.q 


466 
0212 IIIIYOCOCB 
lnld I t r - , r.II I*<< 


/ t/.rl 
he.del 


46, 
0111 11P11011081 
1.L 
h.,.CLOrII.. 
I ..I, 
lp..9 


/ 
frmC. 
"".hlC 


.r* 
O1LS 2lrloorxa 
Lbld ear> I =.LL 
IDCC 
: ,I<fOr 
n l l d s l 


469 
0 2 z . c9 
.*t 


: ssctec """be. 


.,a 
- 


271 
a,, 
47, 
, #"%SZL 


4,. 


/ 
a.n, 
lli*cr. 8 11c5 t CPY h."l 
ro. f".m*C ... 
CYLI... 
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.75 
47s 
022, 
,>,so> 
bbrn*,, 


477 
02zm C , ~ O O O 


.La 
jmp Ib.", 
, c=*e.bc 
c".re"t 
b 
. 
" 
. 
- 
47, 
, ..d 
gO ..tt 
mcOYqh " .*,. 


473 
, CI.iC.l k."l 
.rlrcr 
ra"r,"r 


.no 
((1 
012.m"..r..r..tlii.t 
a. 
-1 ..,. -I,-L.-l,-l..l,., 
: FtI 
(. 
I*,D 


a** 
a>,, ,,,rv,,,,, 


.a, 
db 
-.,-1,.L.-L.-I.-I,.L,., 


.a. 
- 
4 8 3 


486 
.a, 
d..9 
/ follaing ... 
a*.. 
in 
-.lira 
nrnor" 


.*@ 
489 
490 
+.L 
: 
'I.. I/O Lnr*rf.cr 
- 
I . 3 


49, 
.*a 
, 8SLBSX 


49% 


/ 
S I I I C f 0i.L 
I)C%"*. 
Drive -dl 
in <C,. 


4.6 
xnv**e LWL. I.O..d".. 
CO. 
dil"l 


4 3 7 
II f h l . 
L. 
t t r s t .*leal. I.f"." 


4 3 a 
1a.1.. 
01 dl.L 
PII.I.LII 
hl.dl, 
- 
.ss 


3" 
~"L, 


>oa 
S%ldS.. 


SOL 
001r 79121000 
.,< 
I ,<. 
l.di" 


l o 2 
Y O ( 1 r3lrOoI.) 
.-" 
I . = I "", 
n O I 0.d 
n 
, ,."* 
artve . ~ L ~ < c -de 


50, 
00.1 
olo#ooar 
i", a..ats, 
, $a r 
: 
: irearc 
I l t 
i"d<" rO Irm 
d%.Ptcn 
0.1". 
DDdl 
-.b,* 


50. 
00.8 
i D l l l b 6 V 
.,l 
1 i." n , *,. 
8 ID" 1,. 
: 
.k 
'pfO. 


505 
om., 
8.C8 
nr. h 8 .. 
: Ir "D e.Lr" 
3. 
rrbLI. 
no dl.* 
- 
5oa 
urrl i n ~ s o i c z m ," 
..* 
I ."I 
I I jnz natrct..ts.itr.t 
. ...nin. 


5u7 
005, ",Cz 
W.h 
h I .i* 


5.8 
00.9 
>LPE..,.,Z 
,., .... , ... . , ,. ... , .., ... " : :: "::::":.:::'" 
"""' 
$0. 
ODSI >Irrrrlr 
1.1 
h.-r , 0.a 
a 
, ' ( " 0 L W I I .dd, 


110 
0065 7lll6r6r 
ID" *.. 
I 1.. 
)I I I 
n.. 
I -7 
I . . 
; 
*aal..l 
LWln .DYtL.I 


51, 
0069 CDBSa, 


5.2 
omsc E l 
o.II 
I - h l 
Pas b 
; *.I, Lor," 
- 
51, 
"et8r%r.t$se,*ck, 
.lCOlll 
0s" 


$1, 
006D c9 


53, 
.** 


316 
5 x 7 
5,s 
, "rn 


,,3 
/ 
*_I 
..Llle.d 
digr 
T...tld .. $ETT.",O). 
- 
520 
32, 
006s OL000. 


522 
1.1 
h.0 
/ ,..* .. ..I rc.cL 
.e,O 


,a, 
324 
5 2 5 
, 8Bmxx 


326 


P 
set Tract. #a".. 
rr.s. 
.dd?*S. 
rrom ~ n c , 
- 
52, 
3" 11R" r-. 
cY.tle. 
ePi.rlm.. 


328 
529 
007, 8360 
Sste.k, 


007, 2>z,ao 
,I 
1.C , D* )I,b 


511 
00,s 
c, 


.hW *tr, 


5x2 
cet 


53, 
- 
5,. 
539 
, smx 


5,. 
s 
I.I S.CID.. 
I."-. 
.-<La. "".l. er_ 
<a=, 


53, 
I" *.set 
Isr f".lb. 
DpT.f' -... 


538 
539 
007, <,60 
*.tseo 


5.0 
0079 2>V,OO 
m v 1.c 8 ID" h,b 
- 
1 4 1 
OO,C 
C, 
.ma 
*s=cc 


5.2 
rst 


3.3 
5.4 
54, 
, am- 


5.6 


D1.I 
lddle... 
I.".. 
IIU .dd ,..l 


5.7 
I._ 
'BC, 
1. 
1- 
."d 
,oa*. 
to lCa*x 
- 
,a8 


SO th.L 
l"Clhl. 
dl.* opr.r,ona 
t.L1 
.Len 


,a9 
1" ~"~.*"* 
b".. 


550 
5 5 , 
00,s .NO 
..*ma: 


5 5 2 
oa7c >,,,oo 
_" 1.- I .*" h,h 


5 5 , 


sh,d *a". 


55. 
ao.2 
,*>no2 
- 
I S > 


Id. 
l C b . 
: I.1."LI 
O U bml ,. ."... 
". b", 
: I011 mjDYqh to .?( 
ow *."b 
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55. 
55, 
358 
; Jnm*" 


5 5 , 
: 
sec O,., 
*-Dcy 
B."l. 
I."*= 
annt n v n a i 


5eo 


I" 
@ O m " re. t " L " r l dl.* 
0.- 


tra"sr*cs 
- 


561 
56s 
,$, 
0085 >m.m 
,*kb"k 


564 
ma88 c* 


sta 


$65 
568 
56, 
, SECT= 
- 


5sa 
583 


/ 
sl.LOI 
,,.".l.L1. 
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The SCB.ASM module contains the public definitions of the 


various fields in the System Control Block. The 010s can reference 
the public variables. 
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Equates for Mode Byte Bit Fields 
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ACS 8000-15 BlOS Modules 


1.1 
soot m e r M u l e for CP/* 3 
me BOOT.ASM module performs system initialisation other than 
character and disk I/O. 
BOOT loads the CCP for cold starts and 
reloads it for warn starts. 
Note that the device drivers in the 
Digital Research s m p l e 610s initialize devices for a polled, and 
not an interrupt-driven, enviroment. 


k i l l . 
.mar La.a.i 
"-"I. 
tor CN* l.0' 


3 ,, . 
try* 
L 


4 
0000 - 
f.1.. .-" t.". 


I "" - 
'.".,O 
trur 


L i s t r w 1-1. 
Bmt h d e r M u l e for CP/* 3 


CP/M 3 syatela ~ u i d e 
1.1 eoot ~oader 
n o d u l e for C P R 3 


: __ CCI w b... 
0 IOi i.LO.ain. 


2 
2 
, 
1.i ... 
LO.. 
8 
I., 
..m8.. 
: .3... 
3.12.". 
10.. 
1" 0.s. 


LO 
O01C 1~0000.1 
Id. *Sb.L 
I W.h 
P." 


>d,L: 
, I."s 
SYrrenf b.". 


62 
0010 ,..LC00000 
I", 
..kI.lb."l 
I 
2b"k.i 
? ..I.C< 
?PA 


c, 
00,s 
.,. 
I 
p.. 
: 9 
. 
L 
. 
Wee 


6, 
OY,, 
.bOXD000. 
.", 
B . 2 
1 ..,I 
il"l.L 
, ..ll.t 
I.L.. 
b."l 


65 
00,c ,177 


'e 
Q0,E 2,OB 


W e P 
. 
. 
I .-* .,. 
,"= b < dn. b 


i ciarr mr 4t. 


67 
00.0 ,m, 
_" .,b I Dc. 


/ e.,.p 
pinkel, 
d.0P _""l 


68 
00.2 
c2,aao 
in= 
l d l l 
: LIll 
LO. 
don* 


$9 
00.5 
rlC00000 
8. 
I 
9b"b.L 
; I..t0.. 
D.LII..L 
L.". 


70 
00,9 c9 
.et 


rllli 


81 
O O Y ,*OXOnOon 
I", .,I 
1 =.,, 
ll"t.1 
: . 
. 
l 
. 
. 
L 
."LC. 
h."l 


#2 
0061 7zr5 
._ .,. 
8 DY.l 
@.. 
: 
a 4f* 


8 1 
0061 >.~LCDOO~O 
I", 
..Ln.lb.". 
I 
lb"lll 
. .r.rrt 
l P A 


84 
006s ,177 


85 
m 6 A 2308 
m1 D." 
I n- 
I.. 
>"= h , a=. 
b 
, .."* 
fl* 


86 
006C ,se, 
.,b 
8 
= 


/ e.,.p _,"l.l. 
d.OP C D Y " l 


8 , 
msz C25CDO 
jlj 
r l s l 


/ task IOL 
don. 
!! 0 0 1 , C' 


#*Ld". 


,no 
r l o x ~.lAC3"000 
""8 
=,>s , 
-0s 


101 


/ .*L 
d.L. 
rr.".rSc 
.ddrs.(/ 


103 
s~tm",t.. 


LO, 
0010 0.2CCIOIDO 
."i C,.. , ,.P 
MC. 


10. 


; .(f 
rloO1a 


105 
cemd. 


In. 
00.2 
(I<L.C,OIOO 
""i C.20 I ,I. 
bd.. 


,a7 


; 
..CD.dl 


,oa 
10.) 
O D 1 1 ODOIODOA. 1 . ~ ~ 
a* 
Il.lr).l,.lO..C.ll 
YlCsran 
3 . 0 . ...~lr ar~'.11,LO.~ 


1x0 
1 , 
0 
4 
. 
ab 
I,., o:s,os 
ari 
A - no ers.n* l.ir'.o 


112 


LA' 
L23 
oam 
."a 


W"E0 
"" 
6, 
1. 


w 
am$ 
0000 
ooor 
16, 
9, 
1oe 
LO, 
LO' 


CC..S. 
OWC 
I0 
,I 
I. 
1I.I 


CCIUY) 
O O U 
11 
1.1, 


?hLSE 


0002 


X E a " 


0000 
4, 
oow 
3, 
I,', 


ma. 


,II,P,,AU 
OD., 
10 
,I., 


000. 


- 
CP/M 3 system Guide 
1.1 B w t Loader Module for CP/M 3 


CP/M 3 System Guide 
1.2 
Character I/O Handler 


1.2 
Character I/O Bandler for z8O Chipbased System 


=he CHARIO.ASH module performs all character device 


init~alization, 
input, output, and status polling. CHaRIO contains 
the character device characteristlos table. 
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=he DRVTBL.RSM module points to the data structures for each 
configured disk drive. 
he drive table derermlnes which physical 
disk u n i t is associated with which loglcal drive. 
The data 


structure for each disk drive is called an ~xtended irk Parameter 
Header IXDPHI . 
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Module 


~ a m e 


BIOSKmL 


BADRV 
kbbolute logical Drive Code 


QRORV 
Relative logleal drive code (WIT) 


@TRK 
Track Number 


@SECT 
Sector Address 


@ D m 
D m Address 


BDENK 
Bank for Olrk I/O 


@CNT 
Multi-sector Count 


BCBNK 
Current CPU Bank 


CHAR10 


BCTBL 
Character Device Table 


D W T B L 


BDTBL 
Drive Table 


Public 


~ a t a 
~escription 
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26 
TIME 
C-Get/Set Flag None 


27 
SELMBM 
I=Mm Bank 
None 
28 
SETBBR 
R-Mm Bank 
None 


29 
M O V E 
B-Dest Bank 
None 


c=source Bank 


30 
USERP 
Reserved for System Implementor 


31 
RESERV~ 
Reserved for Fvture Use 


32 
RESERVZ 
Reserved for Future Use 
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(continuedl 
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runction 
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Output 
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allocation units. 41 
allocation vector. 34. 88 


see a l s o ALV 


ALO and ALI, 43 
ALV, 34, 38 


banked svaten. 39 
- - - -. 
. 
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double-bit, 
38 
single-bit. 
38 


a a s e n b l e ~ source f i l e . 71 
asaenb1y 1anguqa 


cross-reference program. 
sources, 117 
assembly-tine e r i t h r e t i c , 
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assignment vector, 74 
AUTO OISPmY parameter, 88 
AUTO parameter, 88 
auto-density support, 109 
automatic lagln feature, 41 
AUXIN. 16, 17, 19, 50, 56 
AUXTST. 16, 17, 50, 57 
AUXOST, 16. 17, 50. 58 
AUXOUT, 16. 17, 19. 50. 56 


B 


Backspace, 90 
Bank 


0. 5. 6 
1. 5. 6 
DMA buffer, 76 
selection. 78 
switching. 6 


BANK f i e l d , 44. 46 
bank number 
- - 


current, 24 
bank-switched memory, 1, 6 


block moves and nenorv 


selects. 24 


organization. 8 
requirements, 1. 7 
banked BIOS 


assembling. 69 
linking, 69 
nreoarina. 69 
. . - 
banked ayatan 


allocation vector, 39 
BLNK f i e l d , 46 
BCB data s t r ~ ~ t u l e s . 
46 


BCOS and BIOS, i n common 
memory. 9 


BDOS and SIOS, i n Bank 0, 
buffer control block, 44 
connan memory, 5. 34 
w i t h Bank 1 enabled. 6 


s a s i c Disk operating system 


see BE.% 


&sic Input Output System 


see BIOS, 


baud rate 


current, 32 
s e r i a l devicee, 79 


Bms, 1, 2, 15 


c a l l s t o BIOS. 3, 21 
disk 110, 20 
flags, 3 
Function 44. 52 
E'"ncti0n 49, 3 
Function 50. 16 
JHe, 18 


Binary Coded Decimal (BCDI 


f i e l d s , 31 
format, 25 


BTOS. 1, 2, 15 


aaaembling, 69 
c a l l s , 20 
customizing, 4, 10 
debugging. 100, 103 
disk data structures, 34 
error massage header, 85 
nedla flag, 107, 108 
new funcrione, 113 
routines, 2 
organization. 15 
subroutine entry points, 49. 


84 


subroutines. 17 


BIOS entry points, 15, 49, 77 


cold start. 101 
flush buffere. 64 


BIDS function c a l l s : 
0: 
50, 51. 111, 161 
1: 50, 52. 111, 161 
2: 
50, 55. 111, 161 
3: 
50. 55, 111. 161 
4: 
50. 55, 112. 161 


51 
50, 56, 112, 161 
6: 
50, 56, 112, 161 
7: 
50. 56, 112, 161 


9; 
50. 59. 112, 161 


10: 
50, 59. 112. 161 
11: 50, 60. 112, 161 
121 
50, 60, 112. 161 
13: 
50, 61. 113, 161 
14: 
50, 61. 113. 161 


15s 
50. 57, 113, 161 
16: 
50. 62, 113, 161 
17: 
50, 57, 113, 161 


18, 
50, 57. 113. 161 
19: 
50. 58, 113, 161 
20: 
50, 52, 113, 161 


21% 50, 53. 113, 161 
221 
50. 53, 113, 161 


231 
50, 63. 113. 161 
24: 
50, 64, 113, 161 


251 
50, 65, 113, 161 


261 
24, 50, 67, 113, 162 


function. 3 


CONST, 16, 50, 55 
COPYSYS utility, 98, 102 
CP/M 2 BIOS 


modifiration, 111 


CP/M 3 
linked BIOS Bank/Movc 


Wodule, 152 


cusronizing hardware, 11 
loading into memory, 12 
see a1ao BIDS 


CPM3.SYS. 1 
file. 11. 13. 19 
file format, 115 
loading into memory, 9 8 


CPMLDR. 5. 19, 98, 100 
sign-on message, 101 
utility. 100 


CPNLDR BDOS, 12 
CPMLDRIBIOS, 12 
CPWLDR.CCM, 99 
CTRL-C. 39 
CTRL-Z, 19, 54 
customizing CP/M 3, 11 


data 


b l m k allocation slze, 40 
buffers. 6, 23. 46. 93 
record buffers, 24 
record caching, 23 
region. 10 
data structures. 46, 144 
in commn memory. 6 7 


DOT. 
100 
deblocking buffers. 8, 23 
deblocking logical 128-byte 


records. 23 
debugger. 103 
debugging 


610s. 100. 103 
~12th 
BID, 100. 103 
default value 


with question nark. 8 9 


denairy selection 


automatic, 62 
density-sensing, 59 
device name 


format, 78 


DEVICE utillty, 20, 74 
D N T N T , 16, 17, 50. 53 
DEWBL, 16. 17, 50, 52 


Direct U m r y Access 
See DlUL 


DRYTBL, 17, 50, 53 


JMP, 16 
nodule, 72. 74, 81 


DRYTBL.MM, 
71 


dynamic 


a l l m a t i o n of space. 1 
disk definition table. 59 


equates 


absolute external, 27 
for node Byte Bit Fields, 131 


erasad character, 90 
error 


cede, 24, 31 
handling, 84 
I" nultisector transfer, 63 
nonrecoverable. 85 
error messages 


extended, 1. 30 
i n foreign language. 32 
long. 91 
short, 30 


Extended Diek Parameter 
Header (XDPH), 72, 74, 81 
f i e l d s , 8 3 
format, 82 
Extent mask, 41 


F 


f i l e 


CPM3.m format, 115 
random access, 1 
storage, 10 
S t r Y C t Y r e , 1 
first-rime i n i t i a l i z a t i o n 
code, 83 
flag. 27 
global system, 30 
media, 37 
FLUSH. 16, 50. 64 


O camand, 105 
GmCPM. 6. 11. 12 
command input, 87 
directory hashing, 39 
i n banked system. 87 
i n nonbanked system. 87 
questions, 89, 90 
u t i l i t y , 23, 36. 46, 87 
global variables, 76 


a 


handehaking 


polled, 57. 58 


hardware 


configurations, 2 
i n i t i a l i z a t i o n , 13, 77 
requirements. 1 
eUPPOrted, 10, 11 
special -. 
65 
hardware environment, 2, 10, 


banked aystem, 11 
nonbanked system, 11 
hash table. 39 


directory. 9. 92 
Searches, 107 


head number, 37 
hexadecimal address, 4 
high-order 
b i t . 13 
byte. 27 
nibble. 79 


H M O 16, 50, 58 
I 


i n i t i a l i z a t i o n 
basic system. 51 
cold s t a r t . 12 
hardware, 51, 77 
Page Zero, 18, 51 
system tracks, 102 
input. 140 
inpvr/output 


see I f 0 


interbank moves, 86 
intrabank nares. 86 
I O B ~ E f a c i l i t y . 52 


jump 
address. 16 
instructions, 15. 27. 49 
table, 2 
vector, 15. 16. 77 


L option. 100 
LORBIOS, 12, 51. 100 
length restriction, 100 
linking. 100 


IDRBIOS.A~M. aaae.bling. 
100 


east Recently Used (LFZJI 


buffering, 8. 23 


LINK 


f i e l d . 44 
I option, 100 


LINK-80, 69, 73 
linker. 27 
LIST, 16. 17, 50, 56 
LISTST. 16. 17. 50, 57 
location zero. 6 
logical 


character device 


combination., 
54 


device characteristics. 19 
d e v ~ c e reassigning. 20 
drive. 144 
read operation. 62 
record blocking/deblocking. 


23 


records, 3 
sequential sector 


address. 62 


W I N . 83, 84 
l a - o r d e r 
b i t . 43 
byte. 4 


IRU buffering soheme. 8. 23 
- 
I 


definition-, 46. 133 


media 


automatic type 
- 


determination. 74 
change, 107 
flag, 37, 108 
removable, 107 
- 


memry 


addreeses, 12 
configurations. 1 
contiguous. 6. 11 
~maga. 13 
- 


organization, 6 
selects, 15 
top of banked. 5. 6 


mewry-mapped video 


aleplay. 19 
- 


==mry organization 


banked, 5. 6. 8 
general. 3, 4 
mnbanked, 7-9 
- 


resident, 5 


w a r y requirements, 7 
banked systs., 
7 


nonbanked. 7 
segment table. 92 
- 


m e a ~ y - t o - m e . ~ r y a v e . 86 
m d e 


bltS. 79 
wee, 32 
- 


&;lee 


comounicarion between. 2 
inreracrion., 
73 


M W E . 16. 17. 21. 50. 65 
MOVE.ASM. 71. 73 
nwF ....a,.,- 
" 
. .-""--, -- 
ltrv m i n t s . 86 


interbank. 86 
intrabank, 86 


~ L T T O , 16, 17. 20. 23, 50, 63 


sector read or write 


o w r a t i o n a , 20 


name* 


external. 73 
public. 73 
user-defined. 
73 


nonbank-switched 
memory, 1 


block moves and memory 


selects, 24 
requirements, 1, 7 


"Onbanked BlOS 


assembling, 69 
debugging. 103 
linking, 69 


nonbanked memory, 4 
nonbanked system 


allocation vector, 39 
buffer control block, 44 
c o n f i a r a t i o n , 9 


number of l i n e s per console 


page. 90 


Om f i e l d , 43 
OPEN. 18 
Operating system bank, 9 
Operating system oodvles 


banked. 5 
resident, 5 
Output, 140 
.,"=.-lay 


data buffer, 94 
directory buffer, 93 


P command, 105 
Page Zero. 4, 5, 18. 74 
i n i t i a l i z a t i o n , 18 


PasBpoint. 105 
cold BCOT routine, 105 
i n BIOS. 104 
- . ... 


Password protection, 1 
peripheral 


sinale. 20 
types, 12 


Peripheral device 


110, 2 
reassigning. 20 


physical 


devicea, 20 
dlsk u n i t , 144 
T I " 
7 
-,-. - 


Physical record 


buffers. 107 
mask, 41, 44 
s h i f t factor, 41, 44 


physical sector. 20 
buffers, 23 
count, 76 
transfer, 23 
translation, 62 


PORTS.LIB. 153 
Prlnt Record, 115 
orinters. 11 
public 


data itsne, 159 
definirions, 129 
e n t r y pointa, 157 
nama, 77 
Symbols defined i n modules. 
75 


PUbllc variablca, 129 


names, 17 
predefined, 75 


qusation nark. 88 
question variable. 88 
qYeSti0". 


GENCPM, 89 t o 94 


R 


1-10, 27 
I/Y, 
27 
READ, 16 to 23, 50, 61. 


83. II 
.., .. 


Road-Write r w t i n e a . 23. 24 
R s l B t e r A. 17. 20 
reiovabla arivbe 


810s media flag, 107. 108 
d i r s c t o r v haahin.. 
107 


performahce penai(y;~lo7 


RESERV1, 16, 51 
RESERV2. 16, 51 
Resident System Extenaion (RSX) 


Modules, 8 


I'F~idual mYltiaeCtOr COYnt, 63 
retry routine. 84 


8 
system 


bank, 6 
scs. see system Control Bloel; 
components, 2 


SCB.ASt4. 71 
generation (GBUCPH). 7. 39 
f i l e , 17, 27, 28 
i n i t i a l i z a t i o n , 15, 18. 77 


d u l e , 72. 129 
labels. 27 


scratchpad area, 34, 38 
loader program ICPMLDR), 13 


seceor 
p r i n t e r , 19 


addreas, 37 
start-up, 
3, 11 
skew factors. 37 
rime and date. 15 


SECTRN. 16, so. 62 
system control lack ISCB) 


SELDSK. 21. 23, 50, 59, 109 
deflnitlon, 17 


JHP, 16 
diak organizaeion. 10 
routine. 74, 109 
error node variable, 24 


BBLMEII. 16, 50, 66 
external labels, 27 
separate buffer pools, 8. 23 
f i e l d s , 3 


aequenrial 
system tracks, 10. 18. 19 


f i l e input, 12 
i n i t i a l i z a t i o n , 102 
read, 23 
sample CP/M 3 organization. 


s e r i a l devices. 74 
99 


baud rates, 79 
SETBNK, 16. 23. 50. 66 
SET-. 
16, 20, 21, 23, 50. 60 
SETSEC, 16. 21, 23, 50. 60 
SETTRK. 16, 21, 23. 50. 59 
SID, 100. 103, 105 
G "omand, 1-24 
I command, 104 
L command, 104 
sign-on mesaage. 13, 101 
single-density 
disk handler 180 DM, 144 
floppy diak drive, 11 


&eu factor. 62 
skew table 


addreas, 62 
SKEW macro. 48 
space allocation. 6 
e t a r t i n g 


disk transfer address, 76 
sector, 76 
track, 76 


status polling, 140 
subroutines 


empty, 15 
names. 17 


symbols, public, 75 


t a r g e t system, 12 
TIHE, 16. 17, 50, 67 
time of day 
function, 24 
clacks. 78 


t o p of memory, 5-6. 90 
tracing routines, 105 
track address, 37 
Transient Program Area 


(TPA), 2 . 32 
t r a n s i e n t programs, 5, 18 
TfPE, 83 


UNIT. 8 3 
user interface, 2 
"SEW, 16. 51 


v 


variables 


global, 76 
public, 17. 75. 129 


vecrors 


allocation, Y) 
chedaun, 38 
I/O redlreceion b i t , 54 
redirection, 29 


Warn BOOT routine, 3 
warm start, lo, 137 
WBOOT. 50, 52 
entry point, 52 
JMP, 16 
routine, 18 


WRITE, 16. 20, 21, 23, 50, 61. 


83, 84 


XOPH, 72. 74, 81 
fields, 83 
format. 82 


XHWE, 16, 24, 50, 65, 66 
XoN/XOaa protocol, 32 
XREF, 117 


280 LDIR instruction, 65 


NOTES 
- 
- 


- 
NOTES 


- 


NOTES 
- 
- 


- 
- 
NOTES 


NOTES 


- 
- 
NOTES 


- 


NOTES 


Reader Comment Card 
- We welcome yourcomments and suggerttons.They helpusprovide you with better 
product documentation. 


- 


1. What sections of thir manual are erpecrally helpful? 


2. What suggestions do you have for improving thir manual? What informatmon 


is missing or incomplete? Where are examples needed? 
- 


3. Dld you find errors i n this manual? (Specify secbon and page number.) 
- 


- 
CP/M Plus" (CP/M@ Version 3) Operating System Usefs Guide 
Second Edition: March 1983 
1006-2003-002 


Reader Comment Card 
- We welcome your comments and suggestions They helpusprovide youwith better 
product documentation. 


- 


1. What rectlonr of thxr manual are especially helpful? 
- 


2 What ruggestmonr do you have for improving thlr manual? What rnformation 
- 
is mtssing or ~ncomplete? Where are examples needed? 


- 
3. Dld you find errors in this manual? (Specify section and page number.) 


- 
CP/M Plusm (CP/Me Version 3) Operating System Programmer's Guide 
Second Edition: April 1983 


' 
1006-2023-002 
- 


C O M M W AND -TONS 
BLCCWL I H L PMPUlY OF MOTU RF5LARCH. 


33SS3tlOOVAS OIVd 3 8 l l I M 3 0 V l S O d 


b'd 'S3WlOH 
LSZ'ONlIWtl3d SSVl31StlU 


1IVW Ald3H SS3NISn8 


Reader Comment Card 


We welcome yourcommentr and suggertions.They helpusprov#deyou with better 
product documentation. 


1 What secttons of this manual are erpectally helpful, 


z What ruggest~onr do you have for improving this manual? What information 
is missing or ~ncomplete? Where are examples needed' 


3 Did you find errors tn this manual? (Spec~fy section and page number.) 


CP/M Plus" (CP/MQ Version 3) Operating System System Guide 
Second Edition: July 1983 
1006-2013-002 


BUSINESS REPLY MAIL 
FIRSTCLASS PERMITNO 251 HOLMES. PA 


POSTAGE WILL BE PAID BYADDRESSEE 


Commodore Business Machines 
CP/M Comments 
Box 65 1 
Holmcr. PA 19043 


I(IIII - 
IF MAILED IN THE 
UNITED STATES - 


